From 2a1eba771342f79f63e9831fb810667d15faa812 Mon Sep 17 00:00:00 2001 From: "Vyctor H. Brzezowski" Date: Wed, 12 Aug 2026 00:52:44 -0300 Subject: [PATCH 001/165] fix(ui): show local project icons in the chat header (#122406) * fix(ui): resolve project icons from deterministic paths Prepare project icon bytes during chat startup and serve only the process-stable snapshot. Keep all filesystem work asynchronous and lift the breadcrumb trail onto the topbar's optical axis. * fix(ui): keep project icon paths web-focused Drop the IDE-specific icon convention so every candidate remains an explicit web project path. * fix(ui): preserve project icon compatibility Restore existing web icon paths and refresh bounded session snapshots when they are served. Keep the IDE-specific path excluded per the final product decision. --- .../server-methods/chat-history-handler.ts | 12 ++ src/gateway/workspace-icon-http.test.ts | 101 +++++++++++++++-- src/gateway/workspace-icon-http.ts | 103 ++++++++++++++---- ui/src/e2e/chat-header-axis.e2e.test.ts | 15 ++- ui/src/styles/chat/split-view.css | 4 + 5 files changed, 203 insertions(+), 32 deletions(-) diff --git a/src/gateway/server-methods/chat-history-handler.ts b/src/gateway/server-methods/chat-history-handler.ts index 16dc847821d6..9c8f8b0e6b50 100644 --- a/src/gateway/server-methods/chat-history-handler.ts +++ b/src/gateway/server-methods/chat-history-handler.ts @@ -41,6 +41,7 @@ import { resolveSessionModelRef, resolveSessionStoreKey, } from "../session-utils.js"; +import { prepareSessionWorkspaceIcon } from "../workspace-icon-http.js"; import { scheduleChatHistoryManagedMediaCleanup } from "./chat-assistant-content.js"; import { CHAT_HISTORY_MAX_SINGLE_MESSAGE_BYTES, @@ -246,6 +247,16 @@ async function handleChatHistoryRequest({ return; } } + const workspaceIconPreparation = + method === "chat.startup" + ? prepareSessionWorkspaceIcon({ sessionKey, agentId: sessionAgentId }).catch( + (error: unknown) => { + context.logGateway.debug( + `chat.startup continuing without a workspace icon: ${formatErrorMessage(error)}`, + ); + }, + ) + : Promise.resolve(); const modelCatalogPromise = method === "chat.history" ? (() => { @@ -512,6 +523,7 @@ async function handleChatHistoryRequest({ ...(includeAgentsList && startupAgentsList ? { agentsList: startupAgentsList } : {}), ...(startupMetadata ? { metadata: startupMetadata } : {}), }; + await workspaceIconPreparation; respond(true, payload); } diff --git a/src/gateway/workspace-icon-http.test.ts b/src/gateway/workspace-icon-http.test.ts index a4b0f72f49e7..15803680ff43 100644 --- a/src/gateway/workspace-icon-http.test.ts +++ b/src/gateway/workspace-icon-http.test.ts @@ -33,6 +33,7 @@ vi.mock("./server-methods/sessions-files.js", () => ({ const { clearWorkspaceIconCacheForTest, handleWorkspaceIconHttpRequest, + prepareSessionWorkspaceIcon, resolveWorkspaceIcon, SVG_ICON_MAX_BYTES, WORKSPACE_ICON_MAX_BYTES, @@ -73,22 +74,35 @@ afterEach(async () => { describe("resolveWorkspaceIcon", () => { const conventions = [ + { relative: "favicon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, + { relative: "favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, + { relative: "favicon.png", body: PNG_BYTES, contentType: "image/png" }, { relative: "public/favicon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, { relative: "public/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, { relative: "public/favicon.png", body: PNG_BYTES, contentType: "image/png" }, + { relative: "public/favicon-32.png", body: PNG_BYTES, contentType: "image/png" }, { relative: "public/apple-touch-icon.png", body: PNG_BYTES, contentType: "image/png" }, { relative: "static/favicon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, { relative: "static/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, { relative: "static/favicon.png", body: PNG_BYTES, contentType: "image/png" }, + { relative: "ui/public/favicon-32.png", body: PNG_BYTES, contentType: "image/png" }, + { relative: "ui/public/favicon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, + { relative: "ui/public/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, + { relative: "ui/public/favicon.png", body: PNG_BYTES, contentType: "image/png" }, + { relative: "app/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, + { relative: "app/favicon.png", body: PNG_BYTES, contentType: "image/png" }, { relative: "app/icon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, { relative: "app/icon.png", body: PNG_BYTES, contentType: "image/png" }, - { relative: "app/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, + { relative: "app/icon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, + { relative: "src/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, + { relative: "src/favicon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, + { relative: "src/app/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, { relative: "src/app/icon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, { relative: "src/app/icon.png", body: PNG_BYTES, contentType: "image/png" }, - { relative: "src/app/favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, - { relative: "favicon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, - { relative: "favicon.ico", body: ICO_BYTES, contentType: "image/x-icon" }, - { relative: "favicon.png", body: PNG_BYTES, contentType: "image/png" }, + { relative: "assets/icon.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, + { relative: "assets/icon.png", body: PNG_BYTES, contentType: "image/png" }, + { relative: "assets/logo.svg", body: SVG_BYTES, contentType: "image/svg+xml" }, + { relative: "assets/logo.png", body: PNG_BYTES, contentType: "image/png" }, ] as const; it.each(conventions)("resolves $relative as $contentType", async (convention) => { @@ -99,16 +113,17 @@ describe("resolveWorkspaceIcon", () => { expect(icon?.etag).toMatch(/^"[\w-]+"$/u); }); - it("prefers the framework-specific location over a bare root favicon", async () => { + it("uses the first valid icon in the fixed precedence", async () => { const root = await makeWorkspace({ "favicon.ico": ICO_BYTES, "public/favicon.svg": SVG_BYTES, + "ui/public/favicon-32.png": PNG_BYTES, }); - expect((await resolveWorkspaceIcon(root))?.contentType).toBe("image/svg+xml"); + expect((await resolveWorkspaceIcon(root))?.contentType).toBe("image/x-icon"); }); const rejected = [ - { label: "an unconventional location", files: { "assets/favicon.ico": ICO_BYTES } }, + { label: "an unconventional location", files: { "vendor/favicon.png": PNG_BYTES } }, { label: "an empty file", files: { "favicon.ico": Buffer.alloc(0) } }, { label: "bytes that are not an image", files: { "favicon.ico": Buffer.from("#!/bin/sh\n") } }, { @@ -212,6 +227,7 @@ describe("handleWorkspaceIconHttpRequest", () => { it("serves the session workspace icon with sandboxed asset headers", async () => { const root = await makeWorkspace({ "public/favicon.ico": ICO_BYTES }); mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(root); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:one" }); const response = await fetch(iconRoute("agent:main:one")); expect(mocks.resolveLocalSessionWorkspaceRoot).toHaveBeenCalledWith({ @@ -233,6 +249,7 @@ describe("handleWorkspaceIconHttpRequest", () => { it("revalidates an unchanged icon without resending its bytes", async () => { const root = await makeWorkspace({ "favicon.png": PNG_BYTES }); mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(root); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:one" }); const first = await fetch(iconRoute("agent:main:one")); const etag = first.headers.get("etag"); @@ -249,6 +266,7 @@ describe("handleWorkspaceIconHttpRequest", () => { it("omits the body but keeps the representation headers on HEAD", async () => { const root = await makeWorkspace({ "favicon.png": PNG_BYTES }); mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(root); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:one" }); const response = await fetch(iconRoute("agent:main:one"), { method: "HEAD" }); expect(response.status).toBe(200); @@ -265,11 +283,77 @@ describe("handleWorkspaceIconHttpRequest", () => { mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue( hasWorkspace ? await makeWorkspace({}) : undefined, ); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:one" }); const response = await fetch(iconRoute("agent:main:one")); expect(response.status).toBe(404); expect(response.headers.get("cache-control")).toBe("no-store"); }); + it("keeps a request made before chat startup retryable", async () => { + const response = await fetch(iconRoute("agent:main:one")); + expect(response.status).toBe(503); + expect(response.headers.get("cache-control")).toBe("no-store"); + expect(response.headers.get("retry-after")).toBe("1"); + expect(mocks.resolveLocalSessionWorkspaceRoot).not.toHaveBeenCalled(); + }); + + it("waits for preparation already started by chat startup", async () => { + const root = await makeWorkspace({ "public/favicon.ico": ICO_BYTES }); + mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(root); + + const preparation = prepareSessionWorkspaceIcon({ sessionKey: "agent:main:pending" }); + const responsePromise = fetch(iconRoute("agent:main:pending")); + + await preparation; + const response = await responsePromise; + expect(response.status).toBe(200); + expect(Buffer.from(await response.arrayBuffer()).equals(ICO_BYTES)).toBe(true); + }); + + it("records the fallback when preparation fails", async () => { + mocks.resolveLocalSessionWorkspaceRoot.mockImplementation(() => { + throw new Error("broken workspace metadata"); + }); + await expect(prepareSessionWorkspaceIcon({ sessionKey: "agent:main:broken" })).rejects.toThrow( + "broken workspace metadata", + ); + + const response = await fetch(iconRoute("agent:main:broken")); + expect(response.status).toBe(404); + }); + + it("does no session-store or filesystem resolution in the HTTP request", async () => { + const root = await makeWorkspace({ "ui/public/favicon-32.png": PNG_BYTES }); + mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(root); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:one" }); + mocks.resolveLocalSessionWorkspaceRoot.mockClear(); + await fs.rm(path.join(root, "ui/public/favicon-32.png")); + + const first = await fetch(iconRoute("agent:main:one")); + const second = await fetch(iconRoute("agent:main:one")); + + expect(first.status).toBe(200); + expect(second.status).toBe(200); + expect(Buffer.from(await first.arrayBuffer()).equals(PNG_BYTES)).toBe(true); + expect(Buffer.from(await second.arrayBuffer()).equals(PNG_BYTES)).toBe(true); + expect(mocks.resolveLocalSessionWorkspaceRoot).not.toHaveBeenCalled(); + }); + + it("keeps a recently served session snapshot across bounded-cache eviction", async () => { + const root = await makeWorkspace({ "favicon.png": PNG_BYTES }); + mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(root); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:kept" }); + for (let index = 0; index < 127; index += 1) { + await prepareSessionWorkspaceIcon({ sessionKey: `agent:main:filler-${index}` }); + } + + expect((await fetch(iconRoute("agent:main:kept"))).status).toBe(200); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:newest" }); + + expect((await fetch(iconRoute("agent:main:kept"))).status).toBe(200); + expect((await fetch(iconRoute("agent:main:filler-0"))).status).toBe(503); + }); + const malformed = ["/__openclaw__/workspace-icon/", "/__openclaw__/workspace-icon/a/b"]; it.each(malformed)("claims %s as a 404 instead of falling through", async (pathname) => { @@ -316,6 +400,7 @@ describe("handleWorkspaceIconHttpRequest", () => { // resolveLocalSessionWorkspaceRoot withholds the root for exec-node sessions // so the route can never answer with this Gateway's own project icon. mocks.resolveLocalSessionWorkspaceRoot.mockReturnValue(undefined); + await prepareSessionWorkspaceIcon({ sessionKey: "agent:main:remote" }); const response = await fetch(iconRoute("agent:main:remote")); expect(response.status).toBe(404); expect(response.headers.get("cache-control")).toBe("no-store"); diff --git a/src/gateway/workspace-icon-http.ts b/src/gateway/workspace-icon-http.ts index 0a858219c59e..b9724865a956 100644 --- a/src/gateway/workspace-icon-http.ts +++ b/src/gateway/workspace-icon-http.ts @@ -1,9 +1,10 @@ // Serves a workspace directory's own project icon so the Control UI can render // real project identity instead of a generic folder glyph. import { createHash } from "node:crypto"; -import fs from "node:fs"; +import { close } from "node:fs"; import type { IncomingMessage, ServerResponse } from "node:http"; import path from "node:path"; +import { promisify } from "node:util"; import { fileTypeFromBuffer } from "file-type"; import { openRootFileFollowingParents, @@ -26,28 +27,40 @@ import { import { authorizeOperatorScopesForMethod } from "./method-scopes.js"; /** - * Conventional project icon locations, ordered by framework specificity and then - * by rendering fidelity (vector before raster). Resolution stops at the first - * hit, so this list is the whole filesystem cost of a workspace: keeping it - * bounded is what makes icon lookup a one-time-per-workspace operation. + * Conventional project icon locations in deterministic product precedence. + * Resolution stops at the first valid hit, so this fixed list is the whole + * filesystem cost of opening a workspace and never becomes a recursive scan. */ const WORKSPACE_ICON_RELATIVE_PATHS = [ + "favicon.svg", + "favicon.ico", + "favicon.png", "public/favicon.svg", "public/favicon.ico", "public/favicon.png", + "public/favicon-32.png", "public/apple-touch-icon.png", "static/favicon.svg", "static/favicon.ico", "static/favicon.png", + "ui/public/favicon-32.png", + "ui/public/favicon.svg", + "ui/public/favicon.ico", + "ui/public/favicon.png", + "app/favicon.ico", + "app/favicon.png", "app/icon.svg", "app/icon.png", - "app/favicon.ico", + "app/icon.ico", + "src/favicon.ico", + "src/favicon.svg", + "src/app/favicon.ico", "src/app/icon.svg", "src/app/icon.png", - "src/app/favicon.ico", - "favicon.svg", - "favicon.ico", - "favicon.png", + "assets/icon.svg", + "assets/icon.png", + "assets/logo.svg", + "assets/logo.png", ] as const; /** Icons are small by construction; anything larger is not a favicon. */ @@ -55,8 +68,10 @@ export const WORKSPACE_ICON_MAX_BYTES = 512 * 1024; /** Vector icons are markup the renderer must parse, so they get a tighter cap. */ export const SVG_ICON_MAX_BYTES = 64 * 1024; const WORKSPACE_ICON_CACHE_MAX_ENTRIES = 32; +const SESSION_WORKSPACE_ICON_CACHE_MAX_ENTRIES = 128; const SVG_MIME_TYPE = "image/svg+xml"; const ICO_MIME_TYPE = "image/x-icon"; +const closeFileDescriptor = promisify(close); /** Sniffable raster types the Control UI can render inside an element. */ const ALLOWED_RASTER_ICON_MIME_TYPES = new Set([ @@ -78,9 +93,11 @@ type WorkspaceIcon = { type WorkspaceIconResolution = WorkspaceIcon | null; let workspaceIconCache = new Map>(); +let sessionWorkspaceIconCache = new Map>(); export function clearWorkspaceIconCacheForTest(): void { workspaceIconCache = new Map(); + sessionWorkspaceIconCache = new Map(); } /** @@ -138,7 +155,7 @@ async function readWorkspaceIconCandidate( } catch { return undefined; } finally { - fs.closeSync(opened.fd); + await closeFileDescriptor(opened.fd); } if (body.byteLength === 0) { return undefined; @@ -189,6 +206,41 @@ const getSessionsFilesModule = createLazyRuntimeModule( () => import("./server-methods/sessions-files.js"), ); +/** + * Prepares the immutable icon snapshot while opening a chat. The HTTP asset + * request only reads this map: no session-store or filesystem work is allowed + * on that hot path, and icon changes become visible after Gateway restart. + */ +export async function prepareSessionWorkspaceIcon(params: { + sessionKey: string; + agentId?: string; +}): Promise { + const preparation = (async (): Promise => { + const workspaceRoot = (await getSessionsFilesModule()).resolveLocalSessionWorkspaceRoot(params); + return workspaceRoot ? await resolveWorkspaceIcon(workspaceRoot) : null; + })(); + sessionWorkspaceIconCache.delete(params.sessionKey); + // A failed optional preparation still becomes a stable fallback snapshot; + // the returned promise rejects separately so chat.startup can record it. + sessionWorkspaceIconCache.set( + params.sessionKey, + preparation.catch(() => null), + ); + pruneMapToMaxSize(sessionWorkspaceIconCache, SESSION_WORKSPACE_ICON_CACHE_MAX_ENTRIES); + await preparation; +} + +function readPreparedSessionWorkspaceIcon( + sessionKey: string, +): Promise | undefined { + const prepared = sessionWorkspaceIconCache.get(sessionKey); + if (prepared) { + sessionWorkspaceIconCache.delete(sessionKey); + sessionWorkspaceIconCache.set(sessionKey, prepared); + } + return prepared; +} + /** `matched` claims the response so a malformed key 404s instead of reaching the SPA. */ type WorkspaceIconRequest = { matched: false } | { matched: true; sessionKey: string | null }; @@ -216,9 +268,8 @@ function parseWorkspaceIconRequest( } /** - * Serves the icon of the workspace a session runs in. The request names a - * session, never a path: the served file is whatever the process-cached - * resolution already picked inside that session's own workspace root. + * Serves the icon snapshot prepared when the chat opened. The request names a + * session, never a path, and performs no filesystem or session-store work. */ export async function handleWorkspaceIconHttpRequest( req: IncomingMessage, @@ -272,15 +323,23 @@ export async function handleWorkspaceIconHttpRequest( return true; } - const workspaceRoot = parsed.sessionKey - ? (await getSessionsFilesModule()).resolveLocalSessionWorkspaceRoot({ - sessionKey: parsed.sessionKey, - }) - : undefined; - const icon = workspaceRoot ? await resolveWorkspaceIcon(workspaceRoot) : null; + if (!parsed.sessionKey) { + res.setHeader("cache-control", "no-store"); + respondNotFound(res); + return true; + } + const prepared = readPreparedSessionWorkspaceIcon(parsed.sessionKey); + if (!prepared) { + // The header can paint before chat.startup finishes. Keep this state + // retryable so it cannot be cached as the workspace's resolved fallback. + res.statusCode = 503; + res.setHeader("cache-control", "no-store"); + res.setHeader("retry-after", "1"); + res.end("workspace icon snapshot is not ready"); + return true; + } + const icon = await prepared; if (!icon) { - // A workspace can gain an icon later, and this route has no revalidation - // token for an absent one; caching the miss would hide it until expiry. res.setHeader("cache-control", "no-store"); respondNotFound(res); return true; diff --git a/ui/src/e2e/chat-header-axis.e2e.test.ts b/ui/src/e2e/chat-header-axis.e2e.test.ts index 2d380ebca27d..e99c1fc1bf3b 100644 --- a/ui/src/e2e/chat-header-axis.e2e.test.ts +++ b/ui/src/e2e/chat-header-axis.e2e.test.ts @@ -72,8 +72,19 @@ suite.define(() => { }; }); - for (const center of Object.values(centers)) { - expect(Math.abs(center - centers.nav), JSON.stringify(centers)).toBeLessThanOrEqual(0.1); + expect(Math.abs(centers.search - centers.nav), JSON.stringify(centers)).toBeLessThanOrEqual( + 0.1, + ); + for (const center of [ + centers.projectIcon, + centers.projectText, + centers.separator, + centers.sessionText, + ]) { + // Text and artwork carry more visible weight below their geometric + // boxes than Lucide actions, so the identity trail needs a 1px + // optical lift to share the topbar's perceived horizontal axis. + expect(centers.nav - center, JSON.stringify(centers)).toBeCloseTo(1, 1); } expect(await header.locator(".chat-pane__crumb-sep").count()).toBe(2); const parent = header.locator(".chat-pane__parent-session"); diff --git a/ui/src/styles/chat/split-view.css b/ui/src/styles/chat/split-view.css index c6dd88e2826c..ea702915aa6a 100644 --- a/ui/src/styles/chat/split-view.css +++ b/ui/src/styles/chat/split-view.css @@ -171,6 +171,10 @@ openclaw-chat-pane { flex: 0 1 auto; min-width: 0; align-items: center; + /* Inter's visible glyph mass sits slightly below the 28px action glyphs even + when their CSS boxes share a center. Lift the whole trail as one optical + unit so project icon, labels, and separator meet the chrome centerline. */ + transform: translateY(-1px); /* Both interactive segments pull their 5px hover padding back out of flow, so this gap is the separator's actual optical air on each side. */ gap: 6px; From 630aac9b25ae6f42c760226662d4a7b3d1545f82 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:02:32 -0700 Subject: [PATCH 002/165] feat(onboard): label CLI candidates with subscription vs API-key auth (#122140) Detected Codex/Claude Code CLI candidates now say whether they ride a flat-rate subscription login (ChatGPT, Claude) or a metered API key, so picking one is an informed billing decision for an always-on assistant. Codex classification parses `codex login status` output per codex-rs/cli/src/login.rs; Claude uses prompt-free credential-file and env/apiKeyHelper signals only (never the keychain). Unknown states keep the plain 'logged in'. Display-only: ranking and defaults unchanged. --- src/commands/onboard-inference.test.ts | 58 ++++++++++++++-- src/commands/onboard-inference.ts | 91 ++++++++++++++++++++------ 2 files changed, 124 insertions(+), 25 deletions(-) diff --git a/src/commands/onboard-inference.test.ts b/src/commands/onboard-inference.test.ts index 6f9d424a79b3..39f7e8564f77 100644 --- a/src/commands/onboard-inference.test.ts +++ b/src/commands/onboard-inference.test.ts @@ -131,9 +131,49 @@ describe("detectInferenceBackends", () => { "anthropic-api-key", "claude-cli", ]); - expect(candidates[1]).toMatchObject({ credentials: true, detail: "logged in" }); + expect(candidates[1]).toMatchObject({ + credentials: true, + detail: "logged in · API key (usage-billed)", + }); }); + it("labels a Claude CLI environment key as usage-billed", async () => { + const candidates = await detectInferenceBackends({ + env: { ANTHROPIC_API_KEY: "sk-y" }, + platform: "linux", + deps: { + probeLocalCommand: probeDeps({ claude: true }), + readClaudeCliCredentials: () => null, + }, + }); + + expect(candidates.find((candidate) => candidate.kind === "claude-cli")?.detail).toBe( + "logged in · API key (usage-billed)", + ); + }); + + it.each(["oauth", "token"])( + "labels parsed Claude CLI %s credentials as a subscription", + async (type) => { + const candidates = await detectInferenceBackends({ + env: {}, + platform: "linux", + deps: { + probeLocalCommand: probeDeps({ claude: true }), + readClaudeCliCredentials: () => ({ type }), + }, + }); + + expect(candidates).toMatchObject([ + { + kind: "claude-cli", + credentials: true, + detail: "logged in · Claude subscription", + }, + ]); + }, + ); + it("keeps an Anthropic environment key ahead of unknown Claude credentials", async () => { const candidates = await detectInferenceBackends({ env: { ANTHROPIC_API_KEY: "sk-y" }, @@ -176,7 +216,7 @@ describe("detectInferenceBackends", () => { kind: "claude-cli", credentials: true, detail: - "logged in; Claude Code 2.1.206 is the first published build known to advertise msg_lifecycle_v1; found 2.1.205. OpenClaw verifies this capability at runtime. If this build is rejected, run `claude update`, restart OpenClaw, and retry.", + "logged in · Claude subscription; Claude Code 2.1.206 is the first published build known to advertise msg_lifecycle_v1; found 2.1.205. OpenClaw verifies this capability at runtime. If this build is rejected, run `claude update`, restart OpenClaw, and retry.", }, ]); }); @@ -320,11 +360,19 @@ describe("detectInferenceBackends", () => { ).toBeUndefined(); }); - it("recognizes Codex login status across native credential stores", async () => { + it.each([ + ["ChatGPT", "Logged in using ChatGPT", "logged in · ChatGPT subscription"], + [ + "API key", + "Logged in using an API key - sk-proj-1***23456", + "logged in · API key (usage-billed)", + ], + ["unrecognized auth", "Logged in using access token", "logged in"], + ])("classifies Codex %s login status", async (_auth, loginOutput, expectedDetail) => { const probe = async (command: string, args: string[] = ["--version"]) => ({ command, found: command === "codex", - ...(args[0] === "login" ? {} : { version: "codex 1.0" }), + version: args[0] === "login" ? loginOutput : "codex 1.0", }); const candidates = await detectInferenceBackends({ env: {}, @@ -335,7 +383,7 @@ describe("detectInferenceBackends", () => { }); expect(candidates).toMatchObject([ - { kind: "codex-cli", credentials: true, detail: "logged in" }, + { kind: "codex-cli", credentials: true, detail: expectedDetail }, ]); }); diff --git a/src/commands/onboard-inference.ts b/src/commands/onboard-inference.ts index d7341093e7e4..2ca233c1316d 100644 --- a/src/commands/onboard-inference.ts +++ b/src/commands/onboard-inference.ts @@ -83,33 +83,75 @@ function detectCliCredentialState(params: { return params.platform === "darwin" ? undefined : false; } -function describeCliDetail(credentials: boolean | undefined, loginHint: string): string { - if (credentials === true) { +type CliAuthKind = "api-key" | "chatgpt-subscription" | "claude-subscription"; +type CliLoginState = { credentials: boolean | undefined; authKind?: CliAuthKind }; + +const CLI_AUTH_KIND_LABEL: Record = { + "api-key": "API key (usage-billed)", + "chatgpt-subscription": "ChatGPT subscription", + "claude-subscription": "Claude subscription", +}; + +function describeCliDetail(state: CliLoginState, loginHint: string): string { + if (state.authKind) { + return `logged in · ${CLI_AUTH_KIND_LABEL[state.authKind]}`; + } + if (state.credentials === true) { return "logged in"; } - if (credentials === false) { + if (state.credentials === false) { return `installed, not logged in — ${loginHint}, then check again`; } return "installed"; } +function classifyClaudeCliAuth( + credential: { type: string } | null, + env: NodeJS.ProcessEnv, +): CliAuthKind | undefined { + if (env.ANTHROPIC_API_KEY?.trim() || credential?.type === "api_key_helper") { + return "api-key"; + } + if (credential?.type === "oauth" || credential?.type === "token") { + return "claude-subscription"; + } + return undefined; +} + function describeGeminiCliDetail(credentials: boolean | undefined): string { return credentials === true ? "installed; credentials found" : "installed; login status unavailable"; } +async function classifyCodexLoginStatus( + probe: typeof probeLocalCommand, + command: string, +): Promise { + const status = await probe(command, ["login", "status"], { timeoutMs: 3_000 }); + if (status.error) { + // Codex login status covers its own auth store, not custom model-provider + // credentials. Keep failures indeterminate so the live probe decides usability. + return { credentials: undefined }; + } + if (status.version === "Logged in using ChatGPT") { + return { credentials: true, authKind: "chatgpt-subscription" }; + } + if (/^Logged in using an API key - .+$/u.test(status.version ?? "")) { + return { credentials: true, authKind: "api-key" }; + } + return { credentials: true }; +} + +// Deliberately boolean-shaped: this signature is reachable from the exported +// detectInferenceBackends options type and therefore part of the plugin-sdk +// agent-harness API contract. Widening it would bump the contract hash — the +// rich classification stays module-local in classifyCodexLoginStatus. async function detectCodexLoginState( probe: typeof probeLocalCommand, command: string, ): Promise { - const status = await probe(command, ["login", "status"], { timeoutMs: 3_000 }); - if (!status.error) { - return true; - } - // Codex login status covers its own auth store, not custom model-provider - // credentials. Keep failures indeterminate so the live probe decides usability. - return undefined; + return (await classifyCodexLoginStatus(probe, command)).credentials; } function randomizeClaudeCodexTie( @@ -241,7 +283,10 @@ export async function detectInferenceBackends( if (credentials === true && claudeCredential?.type === "oauth") { subscriptionPromotionEligibleCliKinds.add("claude-cli"); } - const detail = describeCliDetail(credentials, "run `claude auth login`"); + const detail = describeCliDetail( + { credentials, authKind: classifyClaudeCliAuth(claudeCredential, env) }, + "run `claude auth login`", + ); // Only the live init record can prove capability support. Keep backports and // wrappers selectable here even when their version predates the known release. cliCandidates.push({ @@ -261,15 +306,21 @@ export async function detectInferenceBackends( } if (codexProbe.found && !codexProbe.timedOut) { const codexCredential = readCodex(); - const credentials = options.deps?.detectCodexLoginState - ? await options.deps.detectCodexLoginState(probe, codexProbe.command) + const loginState: CliLoginState = options.deps?.detectCodexLoginState + ? { credentials: await options.deps.detectCodexLoginState(probe, codexProbe.command) } : options.deps?.readCodexCliCredentials - ? detectCliCredentialState({ - probe: codexProbe, - hasStoredCredentials: codexCredential !== null, - platform, - }) - : await detectCodexLoginState(probe, codexProbe.command); + ? { + credentials: detectCliCredentialState({ + probe: codexProbe, + hasStoredCredentials: codexCredential !== null, + platform, + }), + ...(codexCredential?.type === "oauth" + ? { authKind: "chatgpt-subscription" as const } + : {}), + } + : await classifyCodexLoginStatus(probe, codexProbe.command); + const credentials = loginState.credentials; // Promote only prompt-free ChatGPT OAuth tokens. Status-only logins may be metered; // keychain-only ChatGPT users conservatively stay usable in the fallback tier. if (credentials === true && codexCredential?.type === "oauth") { @@ -279,7 +330,7 @@ export async function detectInferenceBackends( kind: "codex-cli", modelRef: CODEX_APP_SERVER_DEFAULT_MODEL_REF, label: "Codex", - detail: describeCliDetail(credentials, "run `codex login`"), + detail: describeCliDetail(loginState, "run `codex login`"), ...(credentials === undefined ? {} : { credentials }), }); } From 0e6f38178a2f0c1d6a82118cd24ac9ede055c146 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:08:26 -0700 Subject: [PATCH 003/165] refactor(ui): simplify model effort profile flow (#122412) * refactor(ui): simplify model effort profile flow consolidate the Gateway profile shape, remove New Session's synthetic row, and retain boundary regression coverage. * fix(gateway): preserve thinking projection order Keep deterministic response bytes while consuming the canonical thinking profile. --- .../server-methods/models-list-result.ts | 5 +- src/gateway/session-utils-contracts.ts | 13 ++-- src/gateway/session-utils-model.ts | 30 ++++----- src/gateway/session-utils-store.ts | 7 +- ui/src/lib/chat/thinking.test.ts | 39 ----------- ui/src/lib/chat/thinking.ts | 46 ++++++------- .../chat/components/chat-model-controls.ts | 13 ++-- .../pages/new-session/model-control.test.ts | 64 ------------------- ui/src/pages/new-session/model-control.ts | 16 ++--- 9 files changed, 62 insertions(+), 171 deletions(-) diff --git a/src/gateway/server-methods/models-list-result.ts b/src/gateway/server-methods/models-list-result.ts index 235ad34b73b8..526a7f31606d 100644 --- a/src/gateway/server-methods/models-list-result.ts +++ b/src/gateway/server-methods/models-list-result.ts @@ -453,10 +453,7 @@ async function buildPublicModelsListEntries(params: { return { ...buildPublicModelProjection(entry), ...(agentRuntime ? { agentRuntime } : {}), - ...(thinkingProfile && { - thinkingLevels: thinkingProfile.levels, - thinkingDefault: thinkingProfile.defaultLevel, - }), + ...thinkingProfile, ...(capabilityProvider && params.apiKeyCapabilities?.providers.has(capabilityProvider) ? { apiKeySupported: params.apiKeyCapabilities.providers.get(capabilityProvider) === true, diff --git a/src/gateway/session-utils-contracts.ts b/src/gateway/session-utils-contracts.ts index 438b863a53b9..67d12dcc9ec8 100644 --- a/src/gateway/session-utils-contracts.ts +++ b/src/gateway/session-utils-contracts.ts @@ -6,6 +6,11 @@ import type { resolveSessionModelRef } from "../agents/session-model-ref.js"; import type { SubagentRunReadIndex } from "../agents/subagents/registry/subagent-registry-read.js"; import type { SubagentRunReadRecord } from "../agents/subagents/registry/subagent-registry.types.js"; import type { ThinkLevel, listThinkingLevelOptions } from "../auto-reply/thinking.js"; + +export type GatewayModelThinkingProfile = { + thinkingLevels: ReturnType; + thinkingDefault: ThinkLevel; +}; import type { SessionAcpMeta, SessionEntry } from "../config/sessions.js"; import type { ModelCostConfig } from "../utils/usage-format.js"; @@ -18,13 +23,7 @@ export type SessionListRowContext = { subagentRuns: SubagentRunReadIndex; storeChildSessionsByKey: Map; selectedModelByOverrideRef: Map>; - thinkingMetadataByModelRef: Map< - string, - { - levels: ReturnType; - defaultLevel: ThinkLevel; - } - >; + thinkingMetadataByModelRef: Map; displayModelIdentityByKey: Map; modelCostConfigByModelRef: Map; userProfileIdentityById: Map; diff --git a/src/gateway/session-utils-model.ts b/src/gateway/session-utils-model.ts index d7b56dddf769..9224ec97959a 100644 --- a/src/gateway/session-utils-model.ts +++ b/src/gateway/session-utils-model.ts @@ -44,6 +44,7 @@ import { normalizeAgentId } from "../routing/session-key.js"; import type { GatewayModelCatalogSnapshot } from "./server-model-catalog.types.js"; import { createSessionRowModelCacheKey, + type GatewayModelThinkingProfile, type SessionListRowContext, } from "./session-utils-contracts.js"; import type { GatewaySessionsDefaults, SessionsPatchResult } from "./session-utils.types.js"; @@ -114,10 +115,7 @@ export function resolveGatewayModelThinkingProfile(params: { modelCatalog?: ModelCatalogEntry[]; rowContext?: SessionListRowContext; sessionKey?: string; -}): { - levels: ReturnType; - defaultLevel: ReturnType; -} { +}): GatewayModelThinkingProfile { const catalogEntry = params.modelCatalog ? findModelCatalogEntry(params.modelCatalog, { provider: params.provider, @@ -137,13 +135,13 @@ export function resolveGatewayModelThinkingProfile(params: { }); if (!params.rowContext) { return { - levels: listThinkingLevelOptions( + thinkingLevels: listThinkingLevelOptions( params.provider, params.model, params.modelCatalog, agentRuntime, ), - defaultLevel: resolveGatewaySessionThinkingDefault({ + thinkingDefault: resolveGatewaySessionThinkingDefault({ cfg: params.cfg, provider: params.provider, model: params.model, @@ -162,13 +160,13 @@ export function resolveGatewayModelThinkingProfile(params: { return cached; } const metadata = { - levels: listThinkingLevelOptions( + thinkingLevels: listThinkingLevelOptions( params.provider, params.model, params.modelCatalog, agentRuntime, ), - defaultLevel: resolveGatewaySessionThinkingDefault({ + thinkingDefault: resolveGatewaySessionThinkingDefault({ cfg: params.cfg, provider: params.provider, model: params.model, @@ -264,10 +262,11 @@ export function resolveGatewaySessionThinkingProjectionInternal( return { agentRuntime, thinkingLevel, - effectiveThinkingLevel: thinkingLevel ?? metadata.defaultLevel, - thinkingLevels: metadata.levels, - thinkingOptions: metadata.levels.map((level) => level.label), - thinkingDefault: metadata.defaultLevel, + effectiveThinkingLevel: thinkingLevel ?? metadata.thinkingDefault, + // Preserve the established serialized projection order for byte-stable responses. + thinkingLevels: metadata.thinkingLevels, + thinkingOptions: metadata.thinkingLevels.map((level) => level.label), + thinkingDefault: metadata.thinkingDefault, }; } @@ -309,9 +308,10 @@ export function getSessionDefaults( model: resolved.model ?? null, contextTokens: contextTokens ?? null, agentRuntime, - thinkingLevels: thinkingProfile.levels, - thinkingOptions: thinkingProfile.levels.map((level) => level.label), - thinkingDefault: thinkingProfile.defaultLevel, + // Preserve the established serialized projection order for byte-stable responses. + thinkingLevels: thinkingProfile.thinkingLevels, + thinkingOptions: thinkingProfile.thinkingLevels.map((level) => level.label), + thinkingDefault: thinkingProfile.thinkingDefault, }; } diff --git a/src/gateway/session-utils-store.ts b/src/gateway/session-utils-store.ts index 749ac4bf2248..f047946fda2d 100644 --- a/src/gateway/session-utils-store.ts +++ b/src/gateway/session-utils-store.ts @@ -364,9 +364,10 @@ export function listAgentsForGateway( workspace, workspaceGit, agentRuntime, - thinkingLevels: thinkingProfile.levels, - thinkingOptions: thinkingProfile.levels.map((level) => level.label), - thinkingDefault: thinkingProfile.defaultLevel, + // Preserve the established serialized projection order for byte-stable responses. + thinkingLevels: thinkingProfile.thinkingLevels, + thinkingOptions: thinkingProfile.thinkingLevels.map((level) => level.label), + thinkingDefault: thinkingProfile.thinkingDefault, }, model ? { model } : {}, ); diff --git a/ui/src/lib/chat/thinking.test.ts b/ui/src/lib/chat/thinking.test.ts index 8fac02df7478..f34f47858bff 100644 --- a/ui/src/lib/chat/thinking.test.ts +++ b/ui/src/lib/chat/thinking.test.ts @@ -20,9 +20,6 @@ describe("chat thinking helpers", () => { resolveThinkingLevelInput( "ultra", { - key: "agent:main:main", - kind: "direct", - updatedAt: 1, thinkingLevels: [{ id: "ultra", label: "Ultra" }], }, undefined, @@ -93,40 +90,4 @@ describe("chat thinking helpers", () => { expect(state.options.map((option) => option.value)).not.toContain("ultra"); }); - - it("uses identical reasoning options for a canonical default and explicit selection", () => { - const thinkingLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"].map( - (id) => ({ id, label: id }), - ); - const defaults = { - modelProvider: "openai", - model: "gpt-5.6-sol", - contextTokens: null, - thinkingLevels, - thinkingOptions: thinkingLevels.map((level) => level.label), - thinkingDefault: "medium", - }; - const inherited = resolveChatThinkingSelectState({ - catalog: [{ provider: "openai", id: "gpt-5.6-sol", name: "GPT-5.6 Sol", reasoning: true }], - defaults, - sessionKey: "new-session:main", - session: { key: "new-session:main", kind: "direct", updatedAt: null }, - sessionsResult: null, - }); - const explicit = resolveChatThinkingSelectState({ - catalog: [{ provider: "openai", id: "gpt-5.6-sol", name: "GPT-5.6 Sol", reasoning: true }], - defaults, - sessionKey: "new-session:main", - session: { - key: "new-session:main", - kind: "direct", - updatedAt: null, - modelProvider: "openai", - model: "gpt-5.6-sol", - }, - sessionsResult: null, - }); - - expect(explicit).toEqual(inherited); - }); }); diff --git a/ui/src/lib/chat/thinking.ts b/ui/src/lib/chat/thinking.ts index 12abc748150e..964b1e79f77f 100644 --- a/ui/src/lib/chat/thinking.ts +++ b/ui/src/lib/chat/thinking.ts @@ -16,20 +16,22 @@ import { normalizeLowercaseStringOrEmpty } from "../string-coerce.ts"; type ThinkingSessionDefaults = SessionsListResult["defaults"] | undefined; -type ChatThinkingSelection = - | { - kind: "anchored"; - source: "override" | "default"; - value: string; - displayLabel: string; - index: number; - } - | { - kind: "unanchored"; - source: "override" | "default"; - value: string; - displayLabel: string; - }; +type ChatThinkingSelection = { + source: "override" | "default"; + value: string; + displayLabel: string; +} & ({ kind: "anchored"; index: number } | { kind: "unanchored" }); + +export type ChatThinkingTarget = Pick< + GatewaySessionRow, + | "agentRuntime" + | "model" + | "modelProvider" + | "thinkingDefault" + | "thinkingLevel" + | "thinkingLevels" + | "thinkingOptions" +>; export type ChatThinkingSelectState = { selection: ChatThinkingSelection; @@ -38,7 +40,7 @@ export type ChatThinkingSelectState = { }; function resolveThinkingLevelOptionsForSession( - session: GatewaySessionRow | undefined, + session: ChatThinkingTarget | undefined, defaults: ThinkingSessionDefaults, ): GatewayThinkingLevelOption[] { const { provider, model } = resolveThinkingTargetModel({ defaults, session }); @@ -46,7 +48,7 @@ function resolveThinkingLevelOptionsForSession( } export function formatThinkingCommandOptionsForSession( - session: GatewaySessionRow | undefined, + session: ChatThinkingTarget | undefined, defaults?: SessionsListResult["defaults"], ): string { const options = resolveThinkingLevelOptionsForSession(session, defaults) @@ -57,7 +59,7 @@ export function formatThinkingCommandOptionsForSession( export function resolveThinkingLevelInput( rawLevel: string, - session: GatewaySessionRow | undefined, + session: ChatThinkingTarget | undefined, defaults: ThinkingSessionDefaults, ): string | undefined { const normalized = normalizeThinkLevel(rawLevel); @@ -74,7 +76,7 @@ export function resolveThinkingLevelInput( } export function isThinkingLevelOptionForSession( - session: GatewaySessionRow | undefined, + session: ChatThinkingTarget | undefined, defaults: ThinkingSessionDefaults, level: string, ): boolean { @@ -85,7 +87,7 @@ export function isThinkingLevelOptionForSession( } export function resolveCurrentThinkingLevel( - session: GatewaySessionRow | undefined, + session: ChatThinkingTarget | undefined, defaults: ThinkingSessionDefaults, models: ModelCatalogEntry[], ): string { @@ -143,7 +145,7 @@ function isOffOnlyThinkingLevels(levels: readonly GatewayThinkingLevelOption[]): function resolveThinkingTargetModel(params: { defaults: ThinkingSessionDefaults; - session: GatewaySessionRow | undefined; + session: ChatThinkingTarget | undefined; }): { provider: string | null; model: string | null } { return { provider: params.session?.modelProvider ?? params.defaults?.modelProvider ?? null, @@ -167,7 +169,7 @@ function resolveThinkingLevelOptions(params: { hideUnsupportedOffOnly?: boolean; model: string | null; provider: string | null; - session: GatewaySessionRow | undefined; + session: ChatThinkingTarget | undefined; }): GatewayThinkingLevelOption[] { const modelMatchesDefaults = sessionModelMatchesDefaults(params.session, params.defaults); const catalogEntry = resolveThinkingCatalogEntry(params.catalog, params.provider, params.model); @@ -209,7 +211,7 @@ function resolveThinkingLevelOptions(params: { export function resolveChatThinkingSelectState(params: { catalog: readonly ModelCatalogEntry[]; defaults?: SessionsListResult["defaults"]; - session?: GatewaySessionRow; + session?: ChatThinkingTarget; sessionKey: string; sessionsResult: SessionsListResult | null; }): ChatThinkingSelectState { diff --git a/ui/src/pages/chat/components/chat-model-controls.ts b/ui/src/pages/chat/components/chat-model-controls.ts index 505c6bba2580..bda334b276a4 100644 --- a/ui/src/pages/chat/components/chat-model-controls.ts +++ b/ui/src/pages/chat/components/chat-model-controls.ts @@ -1,10 +1,6 @@ // Chat-owned model, reasoning, and fast-mode picker orchestration. import { html } from "lit"; -import type { - GatewaySessionRow, - ModelCatalogEntry, - SessionsListResult, -} from "../../../api/types.ts"; +import type { ModelCatalogEntry, SessionsListResult } from "../../../api/types.ts"; import { t } from "../../../i18n/index.ts"; import { normalizeChatModelProviderId } from "../../../lib/chat/model-ref.ts"; import { @@ -12,7 +8,10 @@ import { resolveChatModelSelectState, type ChatFastModeSelectValue, } from "../../../lib/chat/model-select-state.ts"; -import { resolveChatThinkingSelectState } from "../../../lib/chat/thinking.ts"; +import { + resolveChatThinkingSelectState, + type ChatThinkingTarget, +} from "../../../lib/chat/thinking.ts"; import { areUiSessionKeysEquivalent } from "../../../lib/sessions/session-key.ts"; import { renderChatEffortPicker } from "./chat-effort-picker.ts"; import { @@ -46,7 +45,7 @@ type ChatModelControlsProps = { sessionsResult: SessionsListResult | null; stream: string | null; thinkingDefaults?: SessionsListResult["defaults"]; - thinkingSession?: GatewaySessionRow; + thinkingSession?: ChatThinkingTarget; onFastModeSelect?: (value: ChatFastModeSelectValue, sessionKey: string) => unknown; onModelSelect?: (value: string, sessionKey: string) => unknown; onModelPickerTargetSelect?: (groupId: string, value: string) => unknown; diff --git a/ui/src/pages/new-session/model-control.test.ts b/ui/src/pages/new-session/model-control.test.ts index c75a415b649a..29c0416d3a58 100644 --- a/ui/src/pages/new-session/model-control.test.ts +++ b/ui/src/pages/new-session/model-control.test.ts @@ -664,70 +664,6 @@ describe("new-session model runtime", () => { }); }); - it("keeps xhigh anchored to the selected model profile across an interactive model switch", async () => { - const levels = (ids: string[]) => ids.map((id) => ({ id, label: id })); - const { context, request } = contextWith([ - { - id: "k3", - name: "Kimi K3", - provider: "kimi", - reasoning: true, - thinkingLevels: levels([ - "off", - "minimal", - "low", - "medium", - "high", - "xhigh", - "max", - "ultra", - ]), - thinkingDefault: "high", - }, - { - id: "gpt-5.6-sol", - name: "GPT-5.6 Sol", - provider: "openai", - reasoning: true, - thinkingLevels: levels(["off", "minimal", "low", "medium", "high", "xhigh", "max"]), - thinkingDefault: "medium", - }, - ]); - const onSelectionChange = vi.fn(); - const control = new NewSessionModelControl(() => undefined, onSelectionChange); - control.load(context, "main", true); - await vi.waitFor(() => { - expect(request).toHaveBeenCalledOnce(); - expect( - renderControl(control, context).querySelector( - '[data-chat-model-option="openai/gpt-5.6-sol"]', - ), - ).not.toBeNull(); - }); - control.selected = "kimi/k3"; - control.thinkingLevel = "xhigh"; - - renderControl(control, context) - .querySelector('[data-chat-model-option="openai/gpt-5.6-sol"]') - ?.click(); - - expect(control.selected).toBe("openai/gpt-5.6-sol"); - expect(control.thinkingLevel).toBe("xhigh"); - expect(onSelectionChange).toHaveBeenLastCalledWith({ - model: "openai/gpt-5.6-sol", - thinkingLevel: "xhigh", - }); - const container = renderControl(control, context); - const slider = container.querySelector('[data-chat-thinking-slider="true"]'); - expect(slider?.dataset.chatThinkingValues).toBe("off,minimal,low,medium,high,xhigh,max"); - expect(slider?.value).toBe("5"); - expect(slider?.max).toBe("6"); - expect(slider?.getAttribute("aria-valuetext")).toBe("Extra high"); - expect( - Number.parseFloat(slider?.style.getPropertyValue("--reasoning-fill") ?? "0"), - ).toBeCloseTo(83.33, 1); - }); - it("clears xhigh when an interactive model switch targets a profile ending at high", async () => { const levels = (ids: string[]) => ids.map((id) => ({ id, label: id })); const { context, request } = contextWith([ diff --git a/ui/src/pages/new-session/model-control.ts b/ui/src/pages/new-session/model-control.ts index b97b2e86dc69..97bf520d180f 100644 --- a/ui/src/pages/new-session/model-control.ts +++ b/ui/src/pages/new-session/model-control.ts @@ -6,7 +6,7 @@ import type { SessionCatalog, SessionsCatalogListResult, } from "../../../../packages/gateway-protocol/src/index.ts"; -import type { GatewayAgentRow, GatewaySessionRow, ModelCatalogEntry } from "../../api/types.ts"; +import type { GatewayAgentRow, ModelCatalogEntry } from "../../api/types.ts"; import type { ApplicationContext } from "../../app/context.ts"; import { t } from "../../i18n/index.ts"; import { @@ -584,14 +584,10 @@ export class NewSessionModelControl { this.catalog, ); const selectedTarget = resolveDraftModelTarget(this.selected, undefined, this.catalog); - const draftRow: GatewaySessionRow = { - key: sessionKey, - kind: "direct", - updatedAt: null, - ...(selectedTarget - ? { model: selectedTarget.model, modelProvider: selectedTarget.provider ?? undefined } - : {}), - ...(this.thinkingLevel ? { thinkingLevel: this.thinkingLevel } : {}), + const thinkingTarget = { + model: selectedTarget?.model, + modelProvider: selectedTarget?.provider ?? undefined, + thinkingLevel: this.thinkingLevel || undefined, }; const thinkingDefaults = { ...sourceResult?.defaults, @@ -639,7 +635,7 @@ export class NewSessionModelControl { showFastMode: false, stream: null, thinkingDefaults, - thinkingSession: draftRow, + thinkingSession: thinkingTarget, onModelSelect: (value) => { this.selectionGeneration += 1; this.restoringPreference = false; From ec4ae78b752e27423497b7c69ead26bf35954698 Mon Sep 17 00:00:00 2001 From: Ayaan Zaidi Date: Wed, 12 Aug 2026 09:42:16 +0530 Subject: [PATCH 004/165] fix(agents): generate session titles with runtime-owned auth (#122163) Use the selected harness for isolated title generation, including native Codex auth. Retry failed dashboard titles from the first user message without overriding manual names. Co-authored-by: Ayaan Zaidi --- .../agent-harness-runtime.json | 2 +- .../agent-harness.json | 2 +- .../plugin-sdk-api-baseline/channel-core.json | 2 +- .../channel-entry-contract.json | 2 +- .../channel-message.json | 2 +- .../channel-outbound.json | 2 +- .../channel-plugin-common.json | 2 +- .../plugin-sdk-api-baseline/core.json | 2 +- .../plugin-sdk-api-baseline/discord.json | 2 +- .../inbound-reply-dispatch.json | 2 +- .../meeting-runtime.json | 2 +- .../plugin-sdk-api-baseline/plugin-entry.json | 2 +- .../plugin-runtime.json | 2 +- .../provider-catalog-runtime.json | 2 +- .../reply-dispatch-runtime.json | 2 +- .../reply-runtime.json | 2 +- .../plugin-sdk-api-baseline/tool-plugin.json | 2 +- .../webhook-ingress.json | 2 +- docs/plugins/sdk-agent-harness.md | 29 +- extensions/codex/harness.test.ts | 89 +++ extensions/codex/harness.ts | 75 +- .../codex/src/app-server/bounded-turn.test.ts | 54 ++ .../codex/src/app-server/bounded-turn.ts | 26 +- .../event-projector-assistant-message.ts | 20 +- .../app-server/isolated-completion.test.ts | 174 +++++ .../src/app-server/isolated-completion.ts | 97 +++ .../src/app-server/settled-turn-finalizer.ts | 1 + .../codex/src/web-search-provider.runtime.ts | 1 + extensions/copilot/harness.test.ts | 109 +-- extensions/copilot/harness.ts | 6 +- extensions/copilot/src/isolated-completion.ts | 57 +- .../src/monitor/thread-title.generate.test.ts | 273 ++------ .../discord/src/monitor/thread-title.ts | 72 +- src/agents/harness/builtin-openclaw.test.ts | 44 +- src/agents/harness/builtin-openclaw.ts | 9 +- src/agents/harness/types.ts | 33 +- src/agents/isolated-completion.test.ts | 392 ++++++++++- src/agents/isolated-completion.ts | 285 +++++++- .../conversation-label-generator.test.ts | 662 ++++-------------- .../reply/conversation-label-generator.ts | 334 +++------ src/gateway/dashboard-session-title.test.ts | 92 ++- src/gateway/dashboard-session-title.ts | 59 +- .../server-methods/chat-send-background.ts | 1 + .../server-methods/session-discussion.test.ts | 22 +- .../server-methods/session-discussion.ts | 33 +- src/plugin-sdk/agent-harness-runtime.test.ts | 9 + 46 files changed, 1837 insertions(+), 1257 deletions(-) create mode 100644 extensions/codex/src/app-server/isolated-completion.test.ts create mode 100644 extensions/codex/src/app-server/isolated-completion.ts diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json index 2a530c0f36a0..57dac44fd419 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json @@ -1 +1 @@ -{"contentHash":"5e739e6ec9fd1a63b1fad71781d063c47b0e2169d8e39cc8cbf21352ed1333f4","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} +{"contentHash":"606504bb06b321f5a4fef507f322c297a9295dccdc2e5996ac64603049113408","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json index 6a77527735c6..2a8b60ee0264 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json @@ -1 +1 @@ -{"contentHash":"7a620697c8689b8ddd08f9d9ec31e54240455158e43277946178caa8b81c3872","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} +{"contentHash":"40d137a31b2ac9f1da776aafcc77b54422b1610c91fe2d6594068e1f7285e91b","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-core.json b/docs/.generated/plugin-sdk-api-baseline/channel-core.json index 00d2a0a258c3..156c909f3056 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-core.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-core.json @@ -1 +1 @@ -{"contentHash":"c462572277db06da0e31193b91fef1ff87682602665148d89fbbf848929f11a9","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} +{"contentHash":"6257c43a60153049dac1af0d828435081f10f6bcd2554e2a67d1c8adb6df973c","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json index f402b1376699..876806d33a11 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json @@ -1 +1 @@ -{"contentHash":"c202b9e8bbbcc1d35d29e9ce92e0d9fd5a08a5a9c2c4c6a4eb6f621a52839da9","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} +{"contentHash":"88113b5ae8119ca780a3d93b0e033c87d0c387b21a29b72e72b375f5c77f08b3","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-message.json b/docs/.generated/plugin-sdk-api-baseline/channel-message.json index 4d2e61f084b9..12d12f0322ff 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-message.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-message.json @@ -1 +1 @@ -{"contentHash":"22a0413c4e79e1c1cd51e122681bf7ad3e7c867668e61dd2f510ea9e14968891","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} +{"contentHash":"a85b4bbcd416a76bde8d58af34fab58bdb416a1b2c8476b46a3ffd8540754e04","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json index 1ded94d41b1d..051fa3974425 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json @@ -1 +1 @@ -{"contentHash":"810a5da4a06925554ab89f9462a17f1fb9fa3196277227eaa383aa82b3b81e58","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} +{"contentHash":"12e07b9ba7b5b35c1f4e0f4510a073adac00671d292a72700025c86376db22b0","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json index 0ebc205b6c16..41cf20d4e926 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json @@ -1 +1 @@ -{"contentHash":"604289da3812346c5a080a9f867a32f4fcc0e06a9837f61395c961d8363d8b9d","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} +{"contentHash":"f36ace33d1e16649ed888032751d5db67e826cdc59f06732a5c13b5185f971ed","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} diff --git a/docs/.generated/plugin-sdk-api-baseline/core.json b/docs/.generated/plugin-sdk-api-baseline/core.json index 581e18aa177d..775825f24dd0 100644 --- a/docs/.generated/plugin-sdk-api-baseline/core.json +++ b/docs/.generated/plugin-sdk-api-baseline/core.json @@ -1 +1 @@ -{"contentHash":"1ecacce44a31327293a1ab1b2e24e3f085e526764f90fbb367687c42e029cce4","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} +{"contentHash":"7451e2a5ffc615f6e8fedebbf4327caf3a64a30973828ca776ca8e298052eebf","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/discord.json b/docs/.generated/plugin-sdk-api-baseline/discord.json index 7c1501dcd9a8..4be0b091d72d 100644 --- a/docs/.generated/plugin-sdk-api-baseline/discord.json +++ b/docs/.generated/plugin-sdk-api-baseline/discord.json @@ -1 +1 @@ -{"contentHash":"b9936060e6ca111906bdca8409097589f8548304b947a7762dc068992f0d2d95","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} +{"contentHash":"726e1cc6c7c0463333587b25908a0b4274c9ca2e1c7d696ab7af5cb392aeca07","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} diff --git a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json index ae7c44a68622..d84bd6799495 100644 --- a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json +++ b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json @@ -1 +1 @@ -{"contentHash":"c7fbb54e9ad926e520df85c396531eadbab78e042ffe315dd3311a3508eb6e55","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} +{"contentHash":"da9273b6213137fdfc3c2f0f22de681c7bd664dfb4fd0fd0f7636b70cad9835b","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} diff --git a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json index e13f7ffbc91c..d024143ffc6d 100644 --- a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json @@ -1 +1 @@ -{"contentHash":"4ea730b41856a414960f55940197485c5b9a80782f7584425eedd8fca585a177","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} +{"contentHash":"2328445ee010703050ecce3ea4b823881172b1da8ffd061cb149a7324ac3b967","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json index af3a0f2510ff..a7e49f33706f 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json @@ -1 +1 @@ -{"contentHash":"6d3f6a64b8ad7459763f4c62a5f731b679ddc64eba4b3463be122659546b2b58","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} +{"contentHash":"cd50a67407a27b36d6f3e22af00940d1031bfe907fc15be5a72187e68f04d822","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json index 9e081752c72e..79ea9f3b1493 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json @@ -1 +1 @@ -{"contentHash":"e7a9ba2f6a48e5c3c2f7cc4a3d6be9d4776deb0c55b4a22084968ad19ad64fbc","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} +{"contentHash":"ba7ea5cfd334e44f5c5c2571a2161961a44f51e64e45074917fab3e69ac7652f","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json index 406cd885b820..8dbf79d536d2 100644 --- a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json @@ -1 +1 @@ -{"contentHash":"a0bbe80276278db6a7f9981d5fb0b2e990438995e76db85d40bf695924e2ad19","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} +{"contentHash":"6f6b852b66e41c6f2c15b617bc00148efbafc2d737049b19b45fe3b25eebb9fe","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/reply-dispatch-runtime.json b/docs/.generated/plugin-sdk-api-baseline/reply-dispatch-runtime.json index d2cfe93ae0eb..577914c7b783 100644 --- a/docs/.generated/plugin-sdk-api-baseline/reply-dispatch-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/reply-dispatch-runtime.json @@ -1 +1 @@ -{"contentHash":"cec5c1bb21caf43610e93817539237330ba78d3ebbe7e21a4218914129a564c2","entrypoint":"reply-dispatch-runtime","importSpecifier":"openclaw/plugin-sdk/reply-dispatch-runtime"} +{"contentHash":"a41c05428a9a5430b2d81ed310aa5efcbeddcef7573adfd8af5ec415bfbbba97","entrypoint":"reply-dispatch-runtime","importSpecifier":"openclaw/plugin-sdk/reply-dispatch-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/reply-runtime.json b/docs/.generated/plugin-sdk-api-baseline/reply-runtime.json index c7eeb7a97fe7..27b48726206c 100644 --- a/docs/.generated/plugin-sdk-api-baseline/reply-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/reply-runtime.json @@ -1 +1 @@ -{"contentHash":"682fa22e552f9663f901c9928b49546cf73a9e91824923c794660672f8de1288","entrypoint":"reply-runtime","importSpecifier":"openclaw/plugin-sdk/reply-runtime"} +{"contentHash":"74f042e649fe9ad18cee1eb327622b526636b470e7c230c2e280e11e990c7764","entrypoint":"reply-runtime","importSpecifier":"openclaw/plugin-sdk/reply-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json index a52f4f826d4b..e7cf05ffec50 100644 --- a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json +++ b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json @@ -1 +1 @@ -{"contentHash":"1759143daf318471c30e816f8651b52ee01c1edbade4f0a9f87b4260b11a21a6","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} +{"contentHash":"0686a3b02b9bae23e46af30fdddf46487db53ec6ffe0833ce9cf298aded54362","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} diff --git a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json index 1d2b55e775cf..3e29106b8dd2 100644 --- a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json +++ b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json @@ -1 +1 @@ -{"contentHash":"1eff4a94da8119d071af4884b96f77fe2b3a73650b9be79bfb2703af510e0a8e","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} +{"contentHash":"80e15361b1e42280548074fc349fd32a45b55dd622c33bc37a0e2db963852790","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index 61a78b2e18a6..4ee0e941b4e6 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -170,12 +170,21 @@ export default definePluginEntry({ ### Isolated completion -The optional `runIsolatedCompletion(params)` capability serves product paths +The optional `runIsolatedCompletionV2(params)` capability serves product paths that require one fresh prompt-only inference call with a literal empty -model-callable tool surface. Core passes the exact prepared `model`, `auth`, -provider, model id, system prompt, user prompt, timeout, abort signal, and stream -parameters. The harness must not re-resolve credentials, switch routes, reuse a -native thread, attach tools, invoke agent lifecycle hooks, or deliver output. +model-callable tool surface. Core passes provider and model ids, prompts, +deadline controls, and one prepared `authorization`: + +- `owner: "host"` contains the exact transport `model` and resolved `auth`. +- `owner: "harness"` contains the prepared runtime auth plan and a credential + snapshot restricted to the single profile selected for that call. Core owns + automatic fallback order and invokes the harness separately for each candidate. + +Host-authorized calls must use the supplied model and credential without +substitution. Harness-authorized calls may resolve only the supplied prepared +route and scoped profiles, or the harness's native account when the plan leaves +auth to the harness. The harness must not switch routes, reuse a native thread, +attach tools, invoke agent lifecycle hooks, or deliver output. Return `{ assistant: AssistantMessage }`. Core accepts only terminal text/thinking content with a `stop` or `length` stop reason; tool calls, failed stops, and empty @@ -187,9 +196,15 @@ Plugin callers select this behavior through the harness callback is the provider-side enforcement SPI, not a second caller API. +The legacy `runIsolatedCompletion(params)` host-auth-only capability is +deprecated and remains available for external plugins through 2026-10-12. +Implement V2 for harness-owned or native authentication; OpenClaw never invents +a host credential when only the legacy capability is present. + Native agent servers often have ambient built-in tools even when OpenClaw sends -an empty tool list. In that case, use a separate provider transport that can -serialize a true zero-tool request, or leave the capability unsupported. +an empty tool list. Disable and attest those native capabilities for the fresh +turn, use a separate transport that can serialize a true zero-tool request, or +leave the capability unsupported. ### Delegated execution diff --git a/extensions/codex/harness.test.ts b/extensions/codex/harness.test.ts index 35e6481eb531..05036ffe2a13 100644 --- a/extensions/codex/harness.test.ts +++ b/extensions/codex/harness.test.ts @@ -6,10 +6,14 @@ import { upsertSessionEntry } from "openclaw/plugin-sdk/session-store-runtime"; import { describe, expect, it, vi } from "vitest"; const completeWithPreparedSimpleCompletionModel = vi.hoisted(() => vi.fn()); +const runCodexIsolatedCompletion = vi.hoisted(() => vi.fn()); vi.mock("openclaw/plugin-sdk/simple-completion-runtime", () => ({ completeWithPreparedSimpleCompletionModel, })); +vi.mock("./src/app-server/isolated-completion.js", () => ({ + runCodexIsolatedCompletion, +})); import { createCodexAppServerAgentHarness } from "./harness.js"; import { @@ -66,6 +70,91 @@ describe("Codex agent harness supports()", () => { ); }); + it("delegates V2 isolated completion to the native bounded adapter", async () => { + const legacyCallCount = completeWithPreparedSimpleCompletionModel.mock.calls.length; + const result = { + assistant: { + role: "assistant", + content: [{ type: "text", text: "done" }], + stopReason: "stop", + }, + }; + runCodexIsolatedCompletion.mockResolvedValueOnce(result); + const params = { + authorization: { + owner: "harness", + plan: { + providerForAuth: "openai", + authProfileProviderForAuth: "openai", + }, + authProfileStore: { version: 1, profiles: {} }, + }, + config: {}, + systemPrompt: "system", + prompt: "user", + timeoutMs: 1_000, + provider: "openai", + modelId: "gpt-test", + agentId: "main", + agentDir: "/tmp/agent", + workspaceDir: "/tmp/workspace", + } as unknown as Parameters>[0]; + + await expect(harness.runIsolatedCompletionV2?.(params)).resolves.toBe(result); + expect(runCodexIsolatedCompletion).toHaveBeenCalledWith(params, { pluginConfig: undefined }); + expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledTimes(legacyCallCount); + }); + + it("keeps V2 host authorization on the prepared direct transport", async () => { + const nativeCallCount = runCodexIsolatedCompletion.mock.calls.length; + const assistant = { + role: "assistant", + content: [{ type: "text", text: "done" }], + stopReason: "stop", + }; + completeWithPreparedSimpleCompletionModel.mockResolvedValueOnce(assistant); + const websocketHarness = createCodexAppServerAgentHarness({ + bindingStore: testCodexAppServerBindingStore, + pluginConfig: { + appServer: { transport: "websocket", url: "ws://127.0.0.1:4501" }, + }, + }); + const hostModel = { + provider: "openai", + id: "gpt-test", + api: "openai-responses", + }; + const hostAuth = { apiKey: "secret", source: "profile:test", mode: "api-key" }; + const params = { + authorization: { + owner: "host", + model: hostModel, + auth: hostAuth, + }, + config: {}, + systemPrompt: "system", + prompt: "user", + timeoutMs: 1_000, + provider: "openai", + modelId: "gpt-test", + agentId: "main", + agentDir: "/tmp/agent", + workspaceDir: "/tmp/workspace", + } as unknown as Parameters>[0]; + + await expect(websocketHarness.runIsolatedCompletionV2?.(params)).resolves.toEqual({ + assistant, + }); + expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledWith( + expect.objectContaining({ + model: hostModel, + auth: hostAuth, + context: expect.objectContaining({ tools: [] }), + }), + ); + expect(runCodexIsolatedCompletion).toHaveBeenCalledTimes(nativeCallCount); + }); + it("supports the canonical codex virtual provider", () => { expect(harness.supports({ provider: "codex", requestedRuntime: "codex" })).toEqual({ supported: true, diff --git a/extensions/codex/harness.ts b/extensions/codex/harness.ts index 72d2f61ca60e..3d43f5ea05bf 100644 --- a/extensions/codex/harness.ts +++ b/extensions/codex/harness.ts @@ -33,6 +33,36 @@ type CodexAppServerAgentHarness = AgentHarnessV2 & { ): Promise; }; +type CodexHostPreparedIsolatedCompletionParams = Parameters< + NonNullable +>[0]; + +async function runCodexHostPreparedIsolatedCompletion( + params: CodexHostPreparedIsolatedCompletionParams, +) { + const timeoutSignal = AbortSignal.timeout(params.timeoutMs); + const signal = params.abortSignal + ? AbortSignal.any([params.abortSignal, timeoutSignal]) + : timeoutSignal; + const assistant = await completeWithPreparedSimpleCompletionModel({ + model: params.model, + auth: params.auth, + cfg: params.config, + context: { + systemPrompt: params.systemPrompt, + messages: [{ role: "user", content: params.prompt, timestamp: Date.now() }], + tools: [], + }, + options: { + maxTokens: params.streamParams?.maxTokens, + temperature: params.streamParams?.temperature, + reasoning: params.thinkLevel, + signal, + }, + }); + return { assistant }; +} + async function disposeSharedCodexAppServerClients(): Promise { const dispose = ( globalThis as typeof globalThis & { @@ -186,31 +216,28 @@ export function createCodexAppServerAgentHarness(options: { nativeHookRelay: { enabled: true }, }); }, - runIsolatedCompletion: async (params) => { - // Codex app-server always exposes update_plan. Pure inference therefore - // uses the already-prepared OpenAI/ChatGPT transport and credential - // directly, without entering a Codex thread or re-resolving the route. - const timeoutSignal = AbortSignal.timeout(params.timeoutMs); - const signal = params.abortSignal - ? AbortSignal.any([params.abortSignal, timeoutSignal]) - : timeoutSignal; - const assistant = await completeWithPreparedSimpleCompletionModel({ - model: params.model, - auth: params.auth, - cfg: params.config, - context: { - systemPrompt: params.systemPrompt, - messages: [{ role: "user", content: params.prompt, timestamp: Date.now() }], - tools: [], - }, - options: { - maxTokens: params.streamParams?.maxTokens, - temperature: params.streamParams?.temperature, - reasoning: params.thinkLevel, - signal, - }, + runIsolatedCompletionV2: async (params) => { + if (params.authorization.owner === "host") { + const { authorization, ...commonParams } = params; + return runCodexHostPreparedIsolatedCompletion({ + ...commonParams, + model: authorization.model, + auth: authorization.auth, + ...(authorization.sourceAuthFingerprint + ? { sourceAuthFingerprint: authorization.sourceAuthFingerprint } + : {}), + }); + } + const { runCodexIsolatedCompletion } = + await import("./src/app-server/isolated-completion.js"); + return runCodexIsolatedCompletion(params, { + pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig, }); - return { assistant }; + }, + runIsolatedCompletion: async (params) => { + // Keep the deprecated V1 contract on its exact host-prepared transport. + // V2 owns native Codex auth and zero-tool attestation above. + return runCodexHostPreparedIsolatedCompletion(params); }, finalizeSettledTurn: async (params) => { const { runCodexSettledTurnFinalization } = diff --git a/extensions/codex/src/app-server/bounded-turn.test.ts b/extensions/codex/src/app-server/bounded-turn.test.ts index bafb0e6b4ee0..fe136b62e6a2 100644 --- a/extensions/codex/src/app-server/bounded-turn.test.ts +++ b/extensions/codex/src/app-server/bounded-turn.test.ts @@ -410,6 +410,56 @@ describe("runBoundedCodexAppServerTurn settled finalization isolation", () => { ).rejects.toThrow("turn ended with status interrupted"); }); + it("forwards one prepared authorization selection to the isolated client", async () => { + const fake = createClientFactory(); + const preparedAuth = { kind: "api-key" as const, apiKey: "test-key" }; + + await runBoundedCodexAppServerTurn({ + model: { mode: "required", id: "gpt-5.4" }, + preparedAuth, + authRequirement: "api-key", + timeoutMs: 5_000, + options: { + clientFactory: fake.factory, + pluginConfig: { appServer: { homeScope: "user" } }, + }, + taskLabel: "isolated completion", + developerInstructions: "Answer only.", + input: [{ type: "text", text: "Name this conversation.", text_elements: [] }], + requiredModalities: ["text"], + isolation: "private-stdio", + requireNoExternalCapabilities: true, + }); + + expect(fake.factory).toHaveBeenCalledWith( + expect.objectContaining({ + preparedAuth, + authRequirement: "api-key", + startOptions: expect.objectContaining({ homeScope: "agent" }), + }), + ); + expect(vi.mocked(fake.factory).mock.calls[0]?.[0]).not.toHaveProperty("authProfileId"); + }); + + it("preserves the configured native model provider when no override is supplied", async () => { + const fake = createClientFactory(); + + await runBoundedCodexAppServerTurn({ + model: { mode: "required", id: "gpt-5.4" }, + timeoutMs: 5_000, + options: { clientFactory: fake.factory }, + taskLabel: "isolated completion", + developerInstructions: "Answer only.", + input: [{ type: "text", text: "Name this conversation.", text_elements: [] }], + requiredModalities: ["text"], + isolation: "configured-transport", + requireNoExternalCapabilities: true, + }); + + const startParams = fake.request.mock.calls.find(([method]) => method === "thread/start")?.[1]; + expect(startParams).not.toHaveProperty("modelProvider"); + }); + it("attests ring-zero and injects frozen history before starting the final turn", async () => { const fake = createClientFactory(); const historyItems: JsonValue[] = [ @@ -465,9 +515,13 @@ describe("runBoundedCodexAppServerTurn settled finalization isolation", () => { "features.hooks": false, "features.multi_agent": false, "features.multi_agent_v2": false, + "features.code_mode": false, + "features.code_mode_only": false, "skills.include_instructions": false, include_environment_context: false, mcp_servers: { inherited: { enabled: false } }, + "tools.experimental_request_user_input.enabled": false, + "tools.update_plan.enabled": false, }, }); const turnParams = fake.request.mock.calls.find(([method]) => method === "turn/start")?.[1]; diff --git a/extensions/codex/src/app-server/bounded-turn.ts b/extensions/codex/src/app-server/bounded-turn.ts index 069bc7084c25..75006a39229f 100644 --- a/extensions/codex/src/app-server/bounded-turn.ts +++ b/extensions/codex/src/app-server/bounded-turn.ts @@ -7,6 +7,7 @@ import { readStringField as readString } from "openclaw/plugin-sdk/string-coerce import { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "openclaw/plugin-sdk/temp-path"; import { CODEX_APP_SERVER_INTERRUPT_TIMEOUT_MS, + closeCodexStartupClientBestEffort, interruptCodexTurnAndWaitBestEffort, } from "./attempt-client-cleanup.js"; import { @@ -14,6 +15,7 @@ import { isTerminalTurnStatus, readCodexNotificationItem, } from "./attempt-notifications.js"; +import type { CodexAppServerAuthRequirement, CodexAppServerPreparedAuth } from "./auth-bridge.js"; import type { CodexAppServerClient } from "./client.js"; import { resolveCodexAppServerRuntimeOptions } from "./config.js"; import { normalizeCodexResponseTokenUsage } from "./event-projector-usage.js"; @@ -95,7 +97,10 @@ class CodexBoundedTurnTimeoutError extends Error { type CodexBoundedTurnParams = { config?: OpenClawConfig; model: CodexBoundedTurnModelSelection; + modelProvider?: string; profile?: string; + preparedAuth?: CodexAppServerPreparedAuth; + authRequirement?: CodexAppServerAuthRequirement; timeoutMs: number; signal?: AbortSignal; agentDir?: string; @@ -163,14 +168,24 @@ async function runBoundedCodexAppServerTurnInWorkspace( // Hosted search needs a private Codex home and cwd so inherited native tools // cannot escape the bounded turn. Media calls retain configured transport // compatibility while still using an isolated ephemeral thread. - const startOptions = workspace.codexHome + const isolatedStartOptions = workspace.codexHome ? buildPrivateCodexAppServerStartOptions(appServer.start, workspace.codexHome) : appServer.start; + // A prepared credential is scoped to the fresh private home even when the + // operator's configured app-server normally points at their user home. + const startOptions = + workspace.codexHome && params.preparedAuth + ? { ...isolatedStartOptions, homeScope: "agent" as const } + : isolatedStartOptions; const ownsClient = !params.options.clientFactory; + const authSelection = params.preparedAuth + ? { preparedAuth: params.preparedAuth } + : { authProfileId: params.profile }; const client = params.options.clientFactory ? await params.options.clientFactory({ startOptions, - authProfileId: params.profile, + ...authSelection, + authRequirement: params.authRequirement, agentDir, config: params.config, timeoutMs, @@ -180,7 +195,8 @@ async function runBoundedCodexAppServerTurnInWorkspace( createIsolatedCodexAppServerClient({ startOptions, timeoutMs, - authProfileId: params.profile, + ...authSelection, + authRequirement: params.authRequirement, agentDir, authProfileStore: params.authProfileStore, config: params.config, @@ -244,7 +260,7 @@ async function runBoundedCodexAppServerTurnInWorkspace( "thread/start", { model, - modelProvider: "openai", + ...(params.modelProvider ? { modelProvider: params.modelProvider } : {}), cwd: workspace.cwd, approvalPolicy: "on-request", sandbox: "read-only", @@ -339,7 +355,7 @@ async function runBoundedCodexAppServerTurnInWorkspace( params.signal?.removeEventListener("abort", abortFromCaller); await interruptPromise; if (ownsClient) { - client.close(); + await closeCodexStartupClientBestEffort(client); } } if (retrySelection) { diff --git a/extensions/codex/src/app-server/event-projector-assistant-message.ts b/extensions/codex/src/app-server/event-projector-assistant-message.ts index b14fca630dbe..3dc5e4cf87e5 100644 --- a/extensions/codex/src/app-server/event-projector-assistant-message.ts +++ b/extensions/codex/src/app-server/event-projector-assistant-message.ts @@ -11,6 +11,11 @@ import { type CodexAssistantMessageParams = CodexLocalRuntimeAttributionParams & Pick; +type CodexAssistantAttribution = { + provider: string; + modelId: string; + api?: AssistantMessage["api"]; +}; type CodexAssistantUsage = Usage & { // Codex is a managed runtime; keep reasoning telemetry private to managed consumers. @@ -44,6 +49,19 @@ export function createAssistantMessage( options: AssistantMessageOptions, ): AssistantMessage { const attribution = resolveCodexLocalRuntimeAttribution(params); + return createAttributedCodexAssistantMessage( + { ...attribution, modelId: params.modelId }, + text, + options, + ); +} + +/** Creates a Codex assistant row when a bounded call already owns attribution. */ +export function createAttributedCodexAssistantMessage( + attribution: CodexAssistantAttribution, + text: string, + options: AssistantMessageOptions, +): AssistantMessage { const usage: CodexAssistantUsage = options.tokenUsage ? { input: options.tokenUsage.input ?? 0, @@ -70,7 +88,7 @@ export function createAssistantMessage( content: [{ type: "text", text }], api: attribution.api ?? "openai-chatgpt-responses", provider: attribution.provider, - model: params.modelId, + model: attribution.modelId, usage, stopReason: options.aborted ? "aborted" : options.promptError ? "error" : "stop", errorMessage: options.promptError ? formatErrorMessage(options.promptError) : undefined, diff --git a/extensions/codex/src/app-server/isolated-completion.test.ts b/extensions/codex/src/app-server/isolated-completion.test.ts new file mode 100644 index 000000000000..23532ce09953 --- /dev/null +++ b/extensions/codex/src/app-server/isolated-completion.test.ts @@ -0,0 +1,174 @@ +import type { AgentHarnessV2 } from "openclaw/plugin-sdk/agent-harness-runtime"; +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const mocks = vi.hoisted(() => ({ + resolveAuthHandoff: vi.fn(), + runBoundedTurn: vi.fn(), +})); + +vi.mock("./auth-bridge.js", () => ({ + resolveCodexAppServerPreparedAuthHandoff: mocks.resolveAuthHandoff, +})); +vi.mock("./bounded-turn.js", () => ({ + runBoundedCodexAppServerTurn: mocks.runBoundedTurn, +})); + +import { runCodexIsolatedCompletion } from "./isolated-completion.js"; + +type IsolatedParams = Parameters>[0]; + +const authProfileStore = { + version: 1, + profiles: { + "openai:test": { + type: "oauth", + provider: "openai", + access: "test-access", + refresh: "test-refresh", + expires: Date.now() + 60_000, + }, + }, +}; + +function createParams(): IsolatedParams { + return { + authorization: { + owner: "harness", + plan: { + providerForAuth: "openai", + authProfileProviderForAuth: "openai", + forwardedAuthProfileId: "openai:test", + modelRoute: { + provider: "openai", + modelId: "gpt-5.4", + api: "openai-responses", + baseUrl: "https://api.openai.com/v1", + authRequirement: "subscription", + requestTransportOverrides: "none", + }, + }, + authProfileStore, + }, + config: {}, + provider: "openai", + modelId: "gpt-5.4", + agentId: "main", + agentDir: "/tmp/agent", + workspaceDir: "/tmp/workspace", + systemPrompt: "Name the conversation.", + prompt: "Help me plan a garden.", + timeoutMs: 5_000, + } as unknown as IsolatedParams; +} + +describe("runCodexIsolatedCompletion", () => { + beforeEach(() => { + mocks.resolveAuthHandoff.mockReset(); + mocks.runBoundedTurn.mockReset(); + mocks.resolveAuthHandoff.mockResolvedValue({ + authProfileId: "openai:test", + nativeAuthProfile: true, + }); + mocks.runBoundedTurn.mockResolvedValue({ + text: "Garden Planning", + model: "gpt-5.4", + usage: { input: 7, output: 3, cacheRead: 2, total: 10 }, + items: [ + { + id: "prompt", + type: "userMessage", + content: [{ type: "text", text: "Help me plan a garden." }], + }, + { id: "reasoning", type: "reasoning" }, + { id: "answer", type: "agentMessage", text: "Garden Planning" }, + ], + }); + }); + + it("uses native authorization on a ring-zero configured-transport turn", async () => { + const params = createParams(); + + await expect(runCodexIsolatedCompletion(params, {})).resolves.toEqual({ + assistant: expect.objectContaining({ + role: "assistant", + api: "openai-chatgpt-responses", + provider: "openai", + model: "gpt-5.4", + content: [{ type: "text", text: "Garden Planning" }], + usage: expect.objectContaining({ + input: 7, + output: 3, + cacheRead: 2, + totalTokens: 10, + }), + }), + }); + expect(mocks.resolveAuthHandoff).toHaveBeenCalledWith( + expect.objectContaining({ + authRequirement: "subscription", + authProfileId: "openai:test", + authProfileStore, + agentDir: "/tmp/agent", + }), + ); + expect(mocks.runBoundedTurn).toHaveBeenCalledWith( + expect.objectContaining({ + model: { mode: "required", id: "gpt-5.4" }, + profile: "openai:test", + authRequirement: "subscription", + isolation: "configured-transport", + requireNoExternalCapabilities: true, + developerInstructions: "Name the conversation.", + input: [{ type: "text", text: "Help me plan a garden.", text_elements: [] }], + }), + ); + expect(mocks.runBoundedTurn.mock.calls[0]?.[0]).not.toHaveProperty("modelProvider"); + }); + + it("forwards prepared profile auth without also selecting a profile", async () => { + const preparedAuth = { + kind: "profile", + profileId: "openai:test", + store: authProfileStore, + snapshot: { + loginParams: { type: "chatgptAuthTokens", accessToken: "test-access" }, + secretFreeCacheKey: "test-account", + }, + }; + mocks.resolveAuthHandoff.mockResolvedValue({ + authProfileId: "openai:test", + nativeAuthProfile: true, + preparedAuth, + }); + + await runCodexIsolatedCompletion(createParams(), {}); + + const boundedParams = mocks.runBoundedTurn.mock.calls[0]?.[0]; + expect(boundedParams).toMatchObject({ preparedAuth }); + expect(boundedParams).not.toHaveProperty("profile"); + }); + + it("rejects any native or tool item outside the passive response surface", async () => { + mocks.runBoundedTurn.mockResolvedValue({ + text: "Garden Planning", + model: "gpt-5.4", + items: [{ id: "tool", type: "commandExecution" }], + }); + + await expect(runCodexIsolatedCompletion(createParams(), {})).rejects.toThrow( + "Codex isolated completion returned unexpected native item: commandExecution", + ); + }); + + it("rejects host authorization at the native-only boundary", async () => { + const params = createParams(); + params.authorization = { + owner: "host", + model: { provider: "openai", id: "gpt-5.4", api: "openai-responses" }, + auth: { mode: "api-key", source: "test" }, + } as IsolatedParams["authorization"]; + + await expect(runCodexIsolatedCompletion(params, {})).rejects.toThrow("harness-owned"); + expect(mocks.runBoundedTurn).not.toHaveBeenCalled(); + }); +}); diff --git a/extensions/codex/src/app-server/isolated-completion.ts b/extensions/codex/src/app-server/isolated-completion.ts new file mode 100644 index 000000000000..b25eea38887b --- /dev/null +++ b/extensions/codex/src/app-server/isolated-completion.ts @@ -0,0 +1,97 @@ +import type { AgentHarnessV2 } from "openclaw/plugin-sdk/agent-harness-runtime"; +import { resolveCodexAppServerPreparedAuthHandoff } from "./auth-bridge.js"; +import { runBoundedCodexAppServerTurn, type CodexBoundedTurnOptions } from "./bounded-turn.js"; +import { readCodexPluginConfig, resolveCodexAppServerHomeScope } from "./config.js"; +import { createAttributedCodexAssistantMessage } from "./event-projector-assistant-message.js"; +import { isJsonObject, type CodexThreadItem } from "./protocol.js"; + +const ISOLATED_PASSIVE_ITEM_TYPES = new Set(["agentMessage", "reasoning"]); + +type CodexIsolatedCompletionParams = Parameters< + NonNullable +>[0]; +type AgentHarnessIsolatedCompletionResult = Awaited< + ReturnType> +>; + +function assertIsolatedCompletionItems(items: CodexThreadItem[], prompt: string): void { + let promptEchoSeen = false; + for (const item of items) { + if (ISOLATED_PASSIVE_ITEM_TYPES.has(item.type)) { + continue; + } + if (item.type === "userMessage" && !promptEchoSeen) { + const content = Array.isArray(item.content) ? item.content : []; + const input = content[0]; + if ( + content.length === 1 && + isJsonObject(input) && + input.type === "text" && + input.text === prompt + ) { + promptEchoSeen = true; + continue; + } + } + throw new Error(`Codex isolated completion returned unexpected native item: ${item.type}`); + } +} + +/** Runs prompt-only Codex inference on an ephemeral, ring-zero native thread. */ +export async function runCodexIsolatedCompletion( + params: CodexIsolatedCompletionParams, + options: CodexBoundedTurnOptions, +): Promise { + const authorization = params.authorization; + if (authorization.owner !== "harness") { + throw new Error("Codex native isolated completion requires harness-owned authorization."); + } + const pluginConfig = readCodexPluginConfig(options.pluginConfig); + const authRequirement = authorization.plan.modelRoute?.authRequirement; + const authHandoff = await resolveCodexAppServerPreparedAuthHandoff({ + authRequirement, + authProfileId: authorization.plan.forwardedAuthProfileId, + authProfileStore: authorization.authProfileStore, + agentDir: params.agentDir, + homeScope: resolveCodexAppServerHomeScope({ appServer: pluginConfig.appServer }), + config: params.config, + subscriptionProfileRequiredError: + "Prepared Codex subscription route requires a scoped native OAuth or token profile.", + subscriptionProfileUnusableError: `Prepared Codex auth profile "${authorization.plan.forwardedAuthProfileId}" is unusable.`, + }); + const authSelection = authHandoff.preparedAuth + ? { preparedAuth: authHandoff.preparedAuth } + : { profile: authHandoff.authProfileId }; + const result = await runBoundedCodexAppServerTurn({ + config: params.config, + model: { + mode: "required", + id: params.modelId, + }, + ...authSelection, + authRequirement, + timeoutMs: params.timeoutMs, + signal: params.abortSignal, + agentDir: params.agentDir, + authProfileStore: authorization.authProfileStore, + options, + taskLabel: "isolated completion", + developerInstructions: params.systemPrompt, + input: [{ type: "text", text: params.prompt, text_elements: [] }], + requiredModalities: ["text"], + isolation: "configured-transport", + requireNoExternalCapabilities: true, + }); + assertIsolatedCompletionItems(result.items, params.prompt); + return { + assistant: createAttributedCodexAssistantMessage( + { + api: "openai-chatgpt-responses", + provider: params.provider, + modelId: result.model, + }, + result.text, + { tokenUsage: result.usage, aborted: false, promptError: null }, + ), + }; +} diff --git a/extensions/codex/src/app-server/settled-turn-finalizer.ts b/extensions/codex/src/app-server/settled-turn-finalizer.ts index 07ec4aeda76c..b0b3ff64324d 100644 --- a/extensions/codex/src/app-server/settled-turn-finalizer.ts +++ b/extensions/codex/src/app-server/settled-turn-finalizer.ts @@ -39,6 +39,7 @@ export async function runCodexSettledTurnFinalization( const bounded = await runBoundedCodexAppServerTurn({ config: attempt.config, model: { mode: "required", id: attempt.modelId }, + modelProvider: "openai", profile: attempt.authProfileId, timeoutMs: attempt.runTimeoutOverrideMs ?? attempt.timeoutMs, signal: attempt.abortSignal, diff --git a/extensions/codex/src/web-search-provider.runtime.ts b/extensions/codex/src/web-search-provider.runtime.ts index 7051c4f7d966..6c2a1d5ff82c 100644 --- a/extensions/codex/src/web-search-provider.runtime.ts +++ b/extensions/codex/src/web-search-provider.runtime.ts @@ -26,6 +26,7 @@ export async function executeCodexWebSearchProviderTool( const result = await runBoundedCodexAppServerTurn({ config: ctx.config, model: { mode: "live-default" }, + modelProvider: "openai", timeoutMs: resolveSearchTimeoutSeconds(ctx.searchConfig as SearchConfigRecord) * 1_000, signal: executionContext?.signal, agentDir: ctx.agentDir, diff --git a/extensions/copilot/harness.test.ts b/extensions/copilot/harness.test.ts index de2015478790..7867d7b1724e 100644 --- a/extensions/copilot/harness.test.ts +++ b/extensions/copilot/harness.test.ts @@ -21,7 +21,7 @@ import { createCopilotTestHostCapabilities } from "./src/host-capability.test-su import type { CopilotClientPool, PoolKey } from "./src/runtime.js"; type AgentHarnessIsolatedCompletionParams = Parameters< - NonNullable + NonNullable >[0]; type CanonicalAttemptResult = Extract; @@ -121,25 +121,28 @@ const TEST_SESSION_CONFIG = { const ISOLATED_COMPLETION_PARAMS = { provider: "github-copilot", modelId: "gpt-4.1", - model: { - id: "gpt-4.1", - name: "GPT-4.1", - api: "openai-responses", - provider: "github-copilot", - baseUrl: "https://api.githubcopilot.com", - reasoning: false, - input: ["text"], - cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, - contextWindow: 128_000, - maxTokens: 8_192, + authorization: { + owner: "host", + model: { + id: "gpt-4.1", + name: "GPT-4.1", + api: "openai-responses", + provider: "github-copilot", + baseUrl: "https://api.githubcopilot.com", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 128_000, + maxTokens: 8_192, + }, + auth: { + apiKey: "prepared-github-token", + profileId: "github:work", + source: "profile", + mode: "oauth", + }, + sourceAuthFingerprint: "prepared-owner-fingerprint", }, - auth: { - apiKey: "prepared-github-token", - profileId: "github:work", - source: "profile", - mode: "oauth", - }, - sourceAuthFingerprint: "prepared-owner-fingerprint", config: {}, agentId: "test", agentDir: "/tmp/agent", @@ -546,7 +549,7 @@ describe("createCopilotAgentHarness", () => { const harness = createCopilotAgentHarness({ pool }); await expect( - harness.runIsolatedCompletion?.({ + harness.runIsolatedCompletionV2?.({ ...ISOLATED_COMPLETION_PARAMS, streamParams: { maxTokens: 800, temperature: 0.2 }, }), @@ -621,6 +624,26 @@ describe("createCopilotAgentHarness", () => { expect(pool.release).toHaveBeenCalledWith(expect.objectContaining({ client })); }); + it("rejects harness-owned authorization before acquiring a client", async () => { + const pool = makePoolMock(); + const harness = createCopilotAgentHarness({ pool }); + + await expect( + harness.runIsolatedCompletionV2?.({ + ...ISOLATED_COMPLETION_PARAMS, + authorization: { + owner: "harness", + plan: { + providerForAuth: "github-copilot", + authProfileProviderForAuth: "github-copilot", + }, + authProfileStore: { version: 1, profiles: {} }, + }, + }), + ).rejects.toThrow("requires host-prepared authorization"); + expect(pool.acquire).not.toHaveBeenCalled(); + }); + it("returns tool-shaped output for core to reject with its stable code", async () => { const session = { abort: vi.fn().mockResolvedValue(undefined), @@ -645,7 +668,7 @@ describe("createCopilotAgentHarness", () => { pool.acquire.mockResolvedValue({ client, key: TEST_POOL_KEY }); const harness = createCopilotAgentHarness({ pool }); - await expect(harness.runIsolatedCompletion?.(ISOLATED_COMPLETION_PARAMS)).resolves.toEqual({ + await expect(harness.runIsolatedCompletionV2?.(ISOLATED_COMPLETION_PARAMS)).resolves.toEqual({ assistant: expect.objectContaining({ content: [{ type: "toolCall", id: "call-1", name: "shell", arguments: {} }], stopReason: "toolUse", @@ -662,7 +685,7 @@ describe("createCopilotAgentHarness", () => { const harness = createCopilotAgentHarness({ pool }); await expect( - harness.runIsolatedCompletion?.({ ...ISOLATED_COMPLETION_PARAMS, thinkLevel }), + harness.runIsolatedCompletionV2?.({ ...ISOLATED_COMPLETION_PARAMS, thinkLevel }), ).rejects.toThrow(`does not support thinking level ${thinkLevel}`); expect(pool.acquire).not.toHaveBeenCalled(); }, @@ -686,7 +709,7 @@ describe("createCopilotAgentHarness", () => { const harness = createCopilotAgentHarness({ pool }); await expect( - harness.runIsolatedCompletion?.({ + harness.runIsolatedCompletionV2?.({ ...ISOLATED_COMPLETION_PARAMS, abortSignal: controller.signal, }), @@ -723,7 +746,7 @@ describe("createCopilotAgentHarness", () => { const harness = createCopilotAgentHarness({ pool }); await expect( - harness.runIsolatedCompletion?.({ + harness.runIsolatedCompletionV2?.({ ...ISOLATED_COMPLETION_PARAMS, abortSignal: controller.signal, }), @@ -744,7 +767,7 @@ describe("createCopilotAgentHarness", () => { const harness = createCopilotAgentHarness({ pool }); await expect( - harness.runIsolatedCompletion?.({ ...ISOLATED_COMPLETION_PARAMS, timeoutMs: 5 }), + harness.runIsolatedCompletionV2?.({ ...ISOLATED_COMPLETION_PARAMS, timeoutMs: 5 }), ).rejects.toThrow("timed out after 5ms"); deferred.resolve(lateHandle); await flushAsyncWork(); @@ -767,7 +790,7 @@ describe("createCopilotAgentHarness", () => { const harness = createCopilotAgentHarness({ pool }); await expect( - harness.runIsolatedCompletion?.({ ...ISOLATED_COMPLETION_PARAMS, timeoutMs: 5 }), + harness.runIsolatedCompletionV2?.({ ...ISOLATED_COMPLETION_PARAMS, timeoutMs: 5 }), ).rejects.toThrow("timed out after 5ms"); deferred.resolve(lateSession); await flushAsyncWork(); @@ -797,7 +820,7 @@ describe("createCopilotAgentHarness", () => { pool.acquire.mockResolvedValue({ client, key: TEST_POOL_KEY }); const harness = createCopilotAgentHarness({ pool }); - await expect(harness.runIsolatedCompletion?.(ISOLATED_COMPLETION_PARAMS)).resolves.toEqual({ + await expect(harness.runIsolatedCompletionV2?.(ISOLATED_COMPLETION_PARAMS)).resolves.toEqual({ assistant: expect.objectContaining({ content: [{ type: "text", text: "Done." }] }), }); expect(disconnect).toHaveBeenCalledOnce(); @@ -825,24 +848,28 @@ describe("createCopilotAgentHarness", () => { ...ISOLATED_COMPLETION_PARAMS, provider: "custom-openai", modelId: "prepared-model", - model: { - ...ISOLATED_COMPLETION_PARAMS.model, - id: "prepared-model", - name: "Prepared model", - provider: "custom-openai", - baseUrl: "https://inference.example/v1", - headers: { "x-tenant": "tenant-a" }, - }, - auth: { - apiKey: "prepared-byok-key", - profileId: "custom:work", - source: "profile", - mode: "api-key" as const, + authorization: { + owner: "host", + model: { + ...ISOLATED_COMPLETION_PARAMS.authorization.model, + id: "prepared-model", + name: "Prepared model", + provider: "custom-openai", + baseUrl: "https://inference.example/v1", + headers: { "x-tenant": "tenant-a" }, + }, + auth: { + apiKey: "prepared-byok-key", + profileId: "custom:work", + source: "profile", + mode: "api-key" as const, + }, + sourceAuthFingerprint: "prepared-owner-fingerprint", }, streamParams: { maxTokens: 321 }, } satisfies AgentHarnessIsolatedCompletionParams; - await expect(harness.runIsolatedCompletion?.(params)).resolves.toEqual({ + await expect(harness.runIsolatedCompletionV2?.(params)).resolves.toEqual({ assistant: expect.objectContaining({ content: [{ type: "text", text: "Done." }], model: "prepared-model", diff --git a/extensions/copilot/harness.ts b/extensions/copilot/harness.ts index 3aa628911fa0..1cef2466c7ef 100644 --- a/extensions/copilot/harness.ts +++ b/extensions/copilot/harness.ts @@ -34,7 +34,7 @@ import type { PoolKey, } from "./src/runtime.js"; -type AgentHarnessIsolatedCompletion = NonNullable; +type AgentHarnessIsolatedCompletion = NonNullable; type AgentHarnessIsolatedCompletionParams = Parameters[0]; type AgentHarnessIsolatedCompletionResult = Awaited>; type CopilotSettledTurnFinalizationAttemptParams = Parameters< @@ -896,7 +896,7 @@ export function createCopilotAgentHarness( } } - async function runIsolatedCompletion( + async function runIsolatedCompletionV2( params: AgentHarnessIsolatedCompletionParams, ): Promise { const completionPromise = (async () => { @@ -974,7 +974,7 @@ export function createCopilotAgentHarness( runAttempt: (params) => runHarnessAttempt(params, "attempt"), - runIsolatedCompletion, + runIsolatedCompletionV2, finalizeSettledTurn: async ({ attempt }) => { const result = await runHarnessAttempt(attempt, "settled-tool-finalization"); diff --git a/extensions/copilot/src/isolated-completion.ts b/extensions/copilot/src/isolated-completion.ts index 2f73b14b3ae8..90533a1585f2 100644 --- a/extensions/copilot/src/isolated-completion.ts +++ b/extensions/copilot/src/isolated-completion.ts @@ -9,7 +9,7 @@ import type { CopilotClientPool, PooledClient } from "./runtime.js"; import { createCopilotIsolatedSessionRestrictions } from "./session-restrictions.js"; import { buildCopilotAssistantUsage } from "./usage-bridge.js"; -type AgentHarnessIsolatedCompletion = NonNullable; +type AgentHarnessIsolatedCompletion = NonNullable; type AgentHarnessIsolatedCompletionParams = Parameters[0]; type AgentHarnessIsolatedCompletionResult = Awaited>; @@ -36,14 +36,6 @@ function startBestEffortCleanup(cleanup: () => Promise): void { } } -function requirePreparedCredential(params: AgentHarnessIsolatedCompletionParams): string { - const apiKey = params.auth.apiKey?.trim(); - if (!apiKey) { - throw new Error("[copilot] isolated completion requires the prepared credential"); - } - return apiKey; -} - function resolveReasoningEffort( thinkLevel: AgentHarnessIsolatedCompletionParams["thinkLevel"], ): SessionConfig["reasoningEffort"] { @@ -175,25 +167,33 @@ export async function runCopilotIsolatedCompletion( deadlineMs: Date.now() + params.timeoutMs, timeoutMs: params.timeoutMs, }; - const apiKey = requirePreparedCredential(params); + if (params.authorization.owner !== "host") { + throw new Error("[copilot] isolated completion requires host-prepared authorization"); + } + const authorization = params.authorization; + const { auth, model } = authorization; + const apiKey = auth.apiKey?.trim(); + if (!apiKey) { + throw new Error("[copilot] isolated completion requires the prepared credential"); + } const resolvedProvider = resolveCopilotProvider({ model: { - api: params.model.api, - id: params.model.id, - provider: params.model.provider, - baseUrl: params.model.baseUrl, - headers: params.model.headers, - authHeader: params.model.authHeader, - contextTokens: params.model.contextTokens, - contextWindow: params.model.contextWindow, - maxTokens: params.streamParams?.maxTokens ?? params.model.maxTokens, + api: model.api, + id: model.id, + provider: model.provider, + baseUrl: model.baseUrl, + headers: model.headers, + authHeader: model.authHeader, + contextTokens: model.contextTokens, + contextWindow: model.contextWindow, + maxTokens: params.streamParams?.maxTokens ?? model.maxTokens, azureApiVersion: - typeof params.model.params?.azureApiVersion === "string" - ? params.model.params.azureApiVersion + typeof model.params?.azureApiVersion === "string" + ? model.params.azureApiVersion : undefined, }, resolvedApiKey: apiKey, - authProfileId: params.auth.profileId, + authProfileId: auth.profileId, }); // Sampling controls are best-effort completion hints. Native Copilot does // not expose equivalent SDK fields, while BYOK applies maxTokens above. @@ -209,8 +209,9 @@ export async function runCopilotIsolatedCompletion( const sessionProvider = byokProxy?.provider ?? resolvedProvider; const githubAuth = sessionProvider.mode === "github-copilot"; const copilotHome = resolve(params.agentDir, "copilot"); - const authProfileId = params.auth.profileId?.trim() || "prepared"; - const authProfileVersion = params.sourceAuthFingerprint?.trim() || tokenFingerprint(apiKey); + const authProfileId = auth.profileId?.trim() || "prepared"; + const authProfileVersion = + authorization.sourceAuthFingerprint?.trim() || tokenFingerprint(apiKey); let handle: PooledClient | undefined; let session: IsolatedSession | undefined; try { @@ -238,7 +239,7 @@ export async function runCopilotIsolatedCompletion( handle = acquiredHandle; const sessionConfig: SessionConfig = { ...createCopilotIsolatedSessionRestrictions(), - model: params.model.id, + model: model.id, ...(githubAuth ? { gitHubToken: apiKey } : {}), ...(sessionProvider.provider ? { provider: sessionProvider.provider } : {}), ...(reasoningEffort ? { reasoningEffort } : {}), @@ -287,9 +288,9 @@ export async function runCopilotIsolatedCompletion( assistant: { role: "assistant", content, - api: params.model.api, - provider: params.model.provider, - model: event.data.model ?? params.model.id, + api: model.api, + provider: model.provider, + model: event.data.model ?? model.id, stopReason: event.data.toolRequests?.length ? "toolUse" : "stop", timestamp: Date.now(), usage: buildCopilotAssistantUsage({ fallbackOutputTokens: event.data.outputTokens }), diff --git a/extensions/discord/src/monitor/thread-title.generate.test.ts b/extensions/discord/src/monitor/thread-title.generate.test.ts index 728ede3a982b..2d8c53208813 100644 --- a/extensions/discord/src/monitor/thread-title.generate.test.ts +++ b/extensions/discord/src/monitor/thread-title.generate.test.ts @@ -1,31 +1,13 @@ // Discord tests cover thread title.generate plugin behavior. -import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; -import { - completeWithPreparedSimpleCompletionModel, - extractAssistantText, - prepareSimpleCompletionModelForAgent, -} from "openclaw/plugin-sdk/simple-completion-runtime"; +import { generateConversationLabel } from "openclaw/plugin-sdk/reply-dispatch-runtime"; import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; import { EMPTY_DISCORD_TEST_CONFIG } from "../test-support/config.js"; -vi.mock("openclaw/plugin-sdk/simple-completion-runtime", { spy: true }); - -const completeWithPreparedSimpleCompletionModelMock = - vi.fn(); -const prepareSimpleCompletionModelForAgentMock = - vi.fn(); -const extractAssistantTextMock = vi.fn(); +vi.mock("openclaw/plugin-sdk/reply-dispatch-runtime", { spy: true }); +const generateConversationLabelMock = vi.fn(); let generateThreadTitle: typeof import("./thread-title.js").generateThreadTitle; -function firstCompletionArgs(): Parameters[0] { - const firstCall = completeWithPreparedSimpleCompletionModelMock.mock.calls.at(0); - if (!firstCall) { - throw new Error("expected completion call"); - } - return firstCall[0]; -} - function hasLoneSurrogate(value: string): boolean { for (let index = 0; index < value.length; index += 1) { const code = value.charCodeAt(index); @@ -35,9 +17,7 @@ function hasLoneSurrogate(value: string): boolean { return true; } index += 1; - continue; - } - if (code >= 0xdc00 && code <= 0xdfff) { + } else if (code >= 0xdc00 && code <= 0xdfff) { return true; } } @@ -50,58 +30,23 @@ beforeAll(async () => { beforeEach(() => { vi.restoreAllMocks(); - completeWithPreparedSimpleCompletionModelMock.mockReset(); - prepareSimpleCompletionModelForAgentMock.mockReset(); - extractAssistantTextMock.mockReset(); - - prepareSimpleCompletionModelForAgentMock.mockResolvedValue({ - selection: { - provider: "anthropic", - modelId: "claude-sonnet-4-6", - agentDir: "/tmp/openclaw-agent", - }, - model: { - provider: "anthropic", - id: "claude-sonnet-4-6", - maxTokens: 64_000, - }, - auth: { - apiKey: "sk-test", - source: "env:TEST_API_KEY", - mode: "api-key", - }, - } as Awaited>); - completeWithPreparedSimpleCompletionModelMock.mockResolvedValue( - {} as Awaited>, - ); - extractAssistantTextMock.mockReturnValue("Generated title"); - vi.mocked(prepareSimpleCompletionModelForAgent).mockImplementation((...args) => - prepareSimpleCompletionModelForAgentMock(...args), - ); - vi.mocked(completeWithPreparedSimpleCompletionModel).mockImplementation((...args) => - completeWithPreparedSimpleCompletionModelMock(...args), - ); - vi.mocked(extractAssistantText).mockImplementation((...args) => - extractAssistantTextMock(...args), + generateConversationLabelMock.mockReset(); + generateConversationLabelMock.mockResolvedValue("Generated title"); + vi.mocked(generateConversationLabel).mockImplementation((...args) => + generateConversationLabelMock(...args), ); }); describe("generateThreadTitle", () => { it.each([ [' "Weekly Release Summary"\nExtra text', "Weekly Release Summary"], - ['\n\n "Weekly Release Summary"\nExtra text', "Weekly Release Summary"], ["```markdown\nWeekly Release Summary\n```", "Weekly Release Summary"], ["**Scaling ArcherScore Development Roadmap**", "Scaling ArcherScore Development Roadmap"], ['"__Weekly Release Summary__"', "Weekly Release Summary"], ["*Plan* for *project*", "*Plan* for *project*"], - ["**Bold** vs **Strong**", "**Bold** vs **Strong**"], - ["_intro_ and _outro_", "_intro_ and _outro_"], - ["**Release *plan***", "Release *plan*"], ["***Release plan***", "Release plan"], - ["__Release _plan___", "Release _plan_"], ])("normalizes generated title %j", async (generated, expected) => { - extractAssistantTextMock.mockReturnValueOnce(generated); - + generateConversationLabelMock.mockResolvedValueOnce(generated); await expect( generateThreadTitle({ cfg: EMPTY_DISCORD_TEST_CONFIG, @@ -111,139 +56,27 @@ describe("generateThreadTitle", () => { ).resolves.toBe(expected); }); - it("calls shared one-shot model prep with aws-sdk allowance", async () => { - prepareSimpleCompletionModelForAgentMock.mockResolvedValueOnce({ - selection: { - provider: "openrouter", - modelId: "anthropic/claude-sonnet-4-5", - profileId: "work", - agentDir: "/tmp/openclaw-agent", - }, - model: { - provider: "openrouter", - id: "anthropic/claude-sonnet-4-5", - maxTokens: 64_000, - }, - auth: { - apiKey: "sk-openrouter", - source: "profile:work", - mode: "api-key", - }, - } as Awaited>); - const cfg = { - agents: { - defaults: { - model: "openrouter/anthropic/claude-sonnet-4-5@work", - }, - }, - } as OpenClawConfig; - + it("routes through the shared isolated label generator", async () => { await generateThreadTitle({ - cfg, - agentId: "main", - messageText: "Need a generated title.", - }); - - expect(prepareSimpleCompletionModelForAgentMock).toHaveBeenCalledWith({ - cfg, - agentId: "main", - useUtilityModel: true, - allowMissingApiKeyModes: ["aws-sdk"], - }); - }); - - it("passes model override refs into shared model prep", async () => { - const cfg = EMPTY_DISCORD_TEST_CONFIG; - await generateThreadTitle({ - cfg, - agentId: "main", - modelRef: "openai/gpt-4.1-mini@local", - messageText: "Need a generated title.", - }); - - expect(prepareSimpleCompletionModelForAgentMock).toHaveBeenCalledWith({ - cfg, - agentId: "main", - modelRef: "openai/gpt-4.1-mini@local", - useUtilityModel: true, - allowMissingApiKeyModes: ["aws-sdk"], - }); - }); - - it("returns null when shared model prep cannot resolve selection", async () => { - prepareSimpleCompletionModelForAgentMock.mockResolvedValueOnce({ - error: "No model configured for agent main.", - } as Awaited>); - - const result = await generateThreadTitle({ cfg: EMPTY_DISCORD_TEST_CONFIG, agentId: "main", - messageText: "Need a thread title.", + modelRef: "openai/gpt-4.1-mini@local", + messageText: "Summarize deployment blockers and owner follow-ups.", + channelName: "release-status", + channelDescription: "Deploy updates and incident notes", }); - expect(result).toBeNull(); - expect(completeWithPreparedSimpleCompletionModelMock).not.toHaveBeenCalled(); - }); - - it("returns null when shared completion prep fails", async () => { - prepareSimpleCompletionModelForAgentMock.mockResolvedValue({ - error: 'No API key resolved for provider "anthropic" (auth mode: api-key).', - selection: { - provider: "anthropic", - modelId: "claude-sonnet-4-6", - agentDir: "/tmp/openclaw-agent", - }, - } as Awaited>); - - const result = await generateThreadTitle({ + expect(generateConversationLabelMock).toHaveBeenCalledWith({ cfg: EMPTY_DISCORD_TEST_CONFIG, agentId: "main", - messageText: "Need a thread title.", - }); - - expect(result).toBeNull(); - expect(completeWithPreparedSimpleCompletionModelMock).not.toHaveBeenCalled(); - }); - - it("builds contextual prompt and forwards completion options", async () => { - const now = 1_700_000_000_000; - const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(now); - const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout"); - let result: string | null; - try { - result = await generateThreadTitle({ - cfg: EMPTY_DISCORD_TEST_CONFIG, - agentId: "main", - messageText: "Summarize deployment blockers and owner follow-ups.", - channelName: "release-status", - channelDescription: "Deploy updates and incident notes", - }); - } finally { - dateNowSpy.mockRestore(); - } - - expect(result).toBe("Generated title"); - expect(completeWithPreparedSimpleCompletionModelMock).toHaveBeenCalledTimes(1); - const completionArgs = firstCompletionArgs(); - expect(completionArgs.context).toEqual({ - systemPrompt: + userMessage: + "Channel: release-status\n\nChannel description: Deploy updates and incident notes\n\nMessage:\nSummarize deployment blockers and owner follow-ups.", + prompt: "Generate a concise Discord thread title (3-6 words). Return only the title. Use channel context when provided and avoid redundant channel-name words unless needed for clarity.", - messages: [ - { - role: "user", - content: - "Channel: release-status\n\nChannel description: Deploy updates and incident notes\n\nMessage:\nSummarize deployment blockers and owner follow-ups.", - timestamp: now, - }, - ], + modelRef: "openai/gpt-4.1-mini@local", + timeoutMs: 60_000, + maxLength: 600, }); - expect(completionArgs.options).toEqual({ - maxTokens: 4_096, - signal: completionArgs.options?.signal, - }); - expect(completionArgs.options?.signal).toBeInstanceOf(AbortSignal); - expect(completionArgs.options).not.toHaveProperty("temperature"); - expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 60_000); }); it("keeps truncated prompt fields on UTF-16 boundaries", async () => { @@ -255,54 +88,32 @@ describe("generateThreadTitle", () => { channelDescription: `${"d".repeat(319)}😀tail`, }); - const message = firstCompletionArgs().context.messages.at(0); - const content = typeof message?.content === "string" ? message.content : ""; - + const content = generateConversationLabelMock.mock.calls[0]?.[0]?.userMessage ?? ""; expect(hasLoneSurrogate(content)).toBe(false); expect(content).toContain(`${"m".repeat(599)}...`); expect(content).toContain(`${"n".repeat(119)}...`); expect(content).toContain(`${"d".repeat(319)}...`); }); - it("clamps completion budget to the selected model output cap", async () => { - prepareSimpleCompletionModelForAgentMock.mockResolvedValueOnce({ - selection: { - provider: "anthropic", - modelId: "claude-haiku-4-5", - agentDir: "/tmp/openclaw-agent", - }, - model: { - provider: "anthropic", - id: "claude-haiku-4-5", - maxTokens: 1_024, - }, - auth: { - apiKey: "sk-test", - source: "env:TEST_API_KEY", - mode: "api-key", - }, - } as Awaited>); - - await generateThreadTitle({ - cfg: EMPTY_DISCORD_TEST_CONFIG, - agentId: "main", - messageText: "Need a generated title.", - }); - - expect(firstCompletionArgs().options?.maxTokens).toBe(1_024); - }); - - it("returns null when completion throws", async () => { - completeWithPreparedSimpleCompletionModelMock.mockRejectedValueOnce( - new Error("network timeout"), - ); - - const result = await generateThreadTitle({ - cfg: EMPTY_DISCORD_TEST_CONFIG, - agentId: "main", - messageText: "Generate title.", - }); - - expect(result).toBeNull(); + it("returns null for empty input, empty output, or generation failure", async () => { + await expect( + generateThreadTitle({ cfg: EMPTY_DISCORD_TEST_CONFIG, agentId: "main", messageText: " " }), + ).resolves.toBeNull(); + generateConversationLabelMock.mockResolvedValueOnce(null); + await expect( + generateThreadTitle({ + cfg: EMPTY_DISCORD_TEST_CONFIG, + agentId: "main", + messageText: "Generate title.", + }), + ).resolves.toBeNull(); + generateConversationLabelMock.mockRejectedValueOnce(new Error("network timeout")); + await expect( + generateThreadTitle({ + cfg: EMPTY_DISCORD_TEST_CONFIG, + agentId: "main", + messageText: "Generate title.", + }), + ).resolves.toBeNull(); }); }); diff --git a/extensions/discord/src/monitor/thread-title.ts b/extensions/discord/src/monitor/thread-title.ts index 579993f5e7b8..a3b7146b4544 100644 --- a/extensions/discord/src/monitor/thread-title.ts +++ b/extensions/discord/src/monitor/thread-title.ts @@ -1,24 +1,13 @@ // Discord plugin module implements thread title behavior. import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +import { generateConversationLabel } from "openclaw/plugin-sdk/reply-dispatch-runtime"; import { logVerbose } from "openclaw/plugin-sdk/runtime-env"; -import { - completeWithPreparedSimpleCompletionModel, - extractAssistantText, - prepareSimpleCompletionModelForAgent, -} from "openclaw/plugin-sdk/simple-completion-runtime"; import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime"; -import { withAbortTimeout } from "./timeouts.js"; const DEFAULT_THREAD_TITLE_TIMEOUT_MS = 60_000; const MAX_THREAD_TITLE_SOURCE_CHARS = 600; const MAX_THREAD_TITLE_CHANNEL_NAME_CHARS = 120; const MAX_THREAD_TITLE_CHANNEL_DESCRIPTION_CHARS = 320; -// Budget generous enough to cover reasoning-model thinking tokens plus the -// short text output. Lower values (e.g. 24) starve reasoning models of output -// capacity: the entire budget is consumed by the thinking block before any -// text is emitted, so extractAssistantText returns empty and the rename is -// silently skipped. -const DISCORD_THREAD_TITLE_MAX_TOKENS = 4_096; const DISCORD_THREAD_TITLE_SYSTEM_PROMPT = "Generate a concise Discord thread title (3-6 words). Return only the title. Use channel context when provided and avoid redundant channel-name words unless needed for clarity."; @@ -36,21 +25,6 @@ export async function generateThreadTitle(params: { return null; } - const prepared = await prepareSimpleCompletionModelForAgent({ - cfg: params.cfg, - agentId: params.agentId, - ...(params.modelRef ? { modelRef: params.modelRef } : {}), - useUtilityModel: true, - allowMissingApiKeyModes: ["aws-sdk"], - }); - if ("error" in prepared) { - const modelLabel = prepared.selection - ? `${prepared.selection.provider}/${prepared.selection.modelId}` - : "unknown"; - logVerbose(`thread-title: ${prepared.error} (agent=${params.agentId}, model=${modelLabel})`); - return null; - } - try { const userMessage = buildThreadTitleCompletionUserMessage({ sourceText, @@ -58,52 +32,22 @@ export async function generateThreadTitle(params: { channelDescription: params.channelDescription, }); const timeoutMs = resolveThreadTitleTimeoutMs(params.timeoutMs); - const response = await completeThreadTitle({ - model: prepared.model, - auth: prepared.auth, + const generated = await generateConversationLabel({ + cfg: params.cfg, + agentId: params.agentId, userMessage, + prompt: DISCORD_THREAD_TITLE_SYSTEM_PROMPT, + ...(params.modelRef ? { modelRef: params.modelRef } : {}), timeoutMs, + maxLength: MAX_THREAD_TITLE_SOURCE_CHARS, }); - const generated = normalizeGeneratedThreadTitle(extractAssistantText(response)); - return generated || null; + return generated ? normalizeGeneratedThreadTitle(generated) : null; } catch (err) { logVerbose(`thread-title: title generation failed for agent ${params.agentId}: ${String(err)}`); return null; } } -async function completeThreadTitle(params: { - model: Parameters[0]["model"]; - auth: Parameters[0]["auth"]; - userMessage: string; - timeoutMs: number; -}) { - const maxTokens = Math.min(DISCORD_THREAD_TITLE_MAX_TOKENS, Math.floor(params.model.maxTokens)); - return await withAbortTimeout({ - timeoutMs: params.timeoutMs, - createTimeoutError: () => new Error(`thread-title timed out after ${params.timeoutMs}ms`), - run: async (signal) => - await completeWithPreparedSimpleCompletionModel({ - model: params.model, - auth: params.auth, - context: { - systemPrompt: DISCORD_THREAD_TITLE_SYSTEM_PROMPT, - messages: [ - { - role: "user", - content: params.userMessage, - timestamp: Date.now(), - }, - ], - }, - options: { - maxTokens, - signal, - }, - }), - }); -} - function buildThreadTitleCompletionUserMessage(params: { sourceText: string; channelName?: string; diff --git a/src/agents/harness/builtin-openclaw.test.ts b/src/agents/harness/builtin-openclaw.test.ts index 9e7214c6389a..a8b80c3cbb2a 100644 --- a/src/agents/harness/builtin-openclaw.test.ts +++ b/src/agents/harness/builtin-openclaw.test.ts @@ -98,8 +98,11 @@ describe("createOpenClawAgentHarness", () => { it("runs isolated completion through the prepared zero-tool transport", async () => { const params = { - model: { provider: "openai", id: "gpt-test", api: "openai-responses" }, - auth: { apiKey: "secret", source: "profile:test", mode: "api-key" }, + authorization: { + owner: "host", + model: { provider: "openai", id: "gpt-test", api: "openai-responses" }, + auth: { apiKey: "secret", source: "profile:test", mode: "api-key" }, + }, config: {}, systemPrompt: "system", prompt: "user", @@ -110,16 +113,16 @@ describe("createOpenClawAgentHarness", () => { agentDir: "/tmp/agent", workspaceDir: "/tmp/workspace", } as unknown as Parameters< - NonNullable["runIsolatedCompletion"]> + NonNullable["runIsolatedCompletionV2"]> >[0]; - await expect(createOpenClawAgentHarness().runIsolatedCompletion?.(params)).resolves.toEqual({ + await expect(createOpenClawAgentHarness().runIsolatedCompletionV2?.(params)).resolves.toEqual({ assistant: expect.objectContaining({ stopReason: "stop" }), }); expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledWith( expect.objectContaining({ - model: params.model, - auth: params.auth, + model: expect.objectContaining({ provider: "openai", id: "gpt-test" }), + auth: expect.objectContaining({ apiKey: "secret", mode: "api-key" }), context: { systemPrompt: "system", messages: [expect.objectContaining({ role: "user", content: "user" })], @@ -129,4 +132,33 @@ describe("createOpenClawAgentHarness", () => { ); expect(runEmbeddedAttempt).not.toHaveBeenCalled(); }); + + it("rejects harness-owned isolated authorization", async () => { + const params = { + authorization: { + owner: "harness", + plan: { + providerForAuth: "openai", + authProfileProviderForAuth: "openai", + }, + authProfileStore: { version: 1, profiles: {} }, + }, + config: {}, + systemPrompt: "system", + prompt: "user", + timeoutMs: 1_000, + provider: "openai", + modelId: "gpt-test", + agentId: "main", + agentDir: "/tmp/agent", + workspaceDir: "/tmp/workspace", + } satisfies Parameters< + NonNullable["runIsolatedCompletionV2"]> + >[0]; + + await expect(createOpenClawAgentHarness().runIsolatedCompletionV2?.(params)).rejects.toThrow( + "requires host-prepared authorization", + ); + expect(completeWithPreparedSimpleCompletionModel).not.toHaveBeenCalled(); + }); }); diff --git a/src/agents/harness/builtin-openclaw.ts b/src/agents/harness/builtin-openclaw.ts index e0fc18589b8b..1256307e6739 100644 --- a/src/agents/harness/builtin-openclaw.ts +++ b/src/agents/harness/builtin-openclaw.ts @@ -85,14 +85,17 @@ export function createOpenClawAgentHarness(): AgentHarnessV2 { contextEngineHostCapabilities: OPENCLAW_EMBEDDED_CONTEXT_ENGINE_HOST.capabilities, supports: () => ({ supported: true, priority: 0 }), runAttempt: (params) => runEmbeddedAttempt(params as EmbeddedRunAttemptParams), - runIsolatedCompletion: async (params) => { + runIsolatedCompletionV2: async (params) => { + if (params.authorization.owner !== "host") { + throw new Error("The built-in OpenClaw harness requires host-prepared authorization."); + } const timeoutSignal = AbortSignal.timeout(params.timeoutMs); const signal = params.abortSignal ? AbortSignal.any([params.abortSignal, timeoutSignal]) : timeoutSignal; const assistant = await completeWithPreparedSimpleCompletionModel({ - model: params.model, - auth: params.auth, + model: params.authorization.model, + auth: params.authorization.auth, cfg: params.config, context: { systemPrompt: params.systemPrompt, diff --git a/src/agents/harness/types.ts b/src/agents/harness/types.ts index 832a26a4e115..4f7816796176 100644 --- a/src/agents/harness/types.ts +++ b/src/agents/harness/types.ts @@ -134,6 +134,7 @@ export type AgentHarnessSettledTurnFinalizationResult = { assistantMessageIndex?: number; diagnosticTrace?: import("../../infra/diagnostic-trace-context.js").DiagnosticTraceContext; }; +/** @deprecated Use AgentHarnessIsolatedCompletionParamsV2. Remove after 2026-10-12. */ type AgentHarnessIsolatedCompletionParams = { /** Logical provider selected by the caller before harness dispatch. */ provider: string; @@ -159,7 +160,29 @@ type AgentHarnessIsolatedCompletionParams = { temperature?: number; }; }; -type AgentHarnessIsolatedCompletionResult = { +export type AgentHarnessIsolatedCompletionAuthorization = + | { + /** OpenClaw resolved the exact transport model and credential before handoff. */ + owner: "host"; + model: import("../../llm/types.js").Model; + auth: import("../model-auth-runtime-shared.js").ResolvedProviderAuth; + /** Non-reversible proof of the prepared credential owner when available. */ + sourceAuthFingerprint?: string; + } + | { + /** The selected harness owns credential resolution for this prepared route. */ + owner: "harness"; + plan: import("../runtime-plan/types.js").AgentRuntimeAuthPlan; + /** Credential snapshot restricted to the single profile selected for this call. */ + authProfileStore: import("../auth-profiles/types.js").AuthProfileStore; + }; +export type AgentHarnessIsolatedCompletionParamsV2 = Omit< + AgentHarnessIsolatedCompletionParams, + "model" | "auth" | "sourceAuthFingerprint" +> & { + authorization: AgentHarnessIsolatedCompletionAuthorization; +}; +export type AgentHarnessIsolatedCompletionResult = { /** The single assistant completion. Core rejects tool-shaped or failed results. */ assistant: import("../../llm/types.js").AssistantMessage; }; @@ -335,12 +358,16 @@ type AgentHarnessRunCapability< finalizeSettledTurn?( params: AgentHarnessSettledTurnFinalizationParams, ): Promise; + /** @deprecated Implement runIsolatedCompletionV2. Remove after 2026-10-12. */ + runIsolatedCompletion?( + params: AgentHarnessIsolatedCompletionParams, + ): Promise; /** * Runs one fresh prompt-only completion with a literal zero-tool model surface. * The harness must fail closed when it cannot enforce that native boundary. */ - runIsolatedCompletion?( - params: AgentHarnessIsolatedCompletionParams, + runIsolatedCompletionV2?( + params: AgentHarnessIsolatedCompletionParamsV2, ): Promise; }; diff --git a/src/agents/isolated-completion.test.ts b/src/agents/isolated-completion.test.ts index c2f60eec9a91..c2cffa3ae035 100644 --- a/src/agents/isolated-completion.test.ts +++ b/src/agents/isolated-completion.test.ts @@ -8,8 +8,11 @@ const mocks = vi.hoisted(() => ({ acquireAgentRunPreparedModelRuntime: vi.fn(), ensureSelectedAgentHarnessPlugin: vi.fn(async () => {}), getRegisteredAgentHarness: vi.fn(), + ensureAuthProfileStore: vi.fn(), isCliRuntimeAliasForProvider: vi.fn(() => false), prepareSimpleCompletionModel: vi.fn(), + prepareAgentRuntimeAuth: vi.fn(), + resolveModelWithRegistry: vi.fn(), resolveCliRuntimeCanonicalProvider: vi.fn(() => undefined), resolveCliBackendConfig: vi.fn< () => { config: { command: string; modelAliases?: Record } } | undefined @@ -32,6 +35,9 @@ vi.mock("./cli-backends.js", () => ({ vi.mock("./embedded-agent-runner/cli-backend-dispatch-eligibility.js", () => ({ resolveEmbeddedCliBackendDispatchEligibility: mocks.resolveEmbeddedCliBackendDispatchEligibility, })); +vi.mock("./embedded-agent-runner/model.js", () => ({ + resolveModelWithRegistry: mocks.resolveModelWithRegistry, +})); vi.mock("./harness/registry.js", () => ({ getRegisteredAgentHarness: mocks.getRegisteredAgentHarness, })); @@ -42,12 +48,33 @@ vi.mock("./model-runtime-aliases.js", () => ({ isCliRuntimeAliasForProvider: mocks.isCliRuntimeAliasForProvider, resolveCliRuntimeExecutionProvider: mocks.resolveCliRuntimeExecutionProvider, })); +vi.mock("./model-auth.js", () => ({ ensureAuthProfileStore: mocks.ensureAuthProfileStore })); vi.mock("./prepared-model-runtime.js", () => ({ acquireAgentRunPreparedModelRuntime: mocks.acquireAgentRunPreparedModelRuntime, })); vi.mock("./simple-completion-runtime.js", () => ({ prepareSimpleCompletionModel: mocks.prepareSimpleCompletionModel, })); +vi.mock("./runtime-plan/prepare-auth.js", async () => { + const actual = await vi.importActual( + "./runtime-plan/prepare-auth.js", + ); + return { ...actual, prepareAgentRuntimeAuth: mocks.prepareAgentRuntimeAuth }; +}); +vi.mock("./runtime-plan/resolve-auth.js", () => ({ + scopeAuthProfileStoreToPreparedPlan: ( + store: { version: number; profiles: Record }, + plan: { forwardedAuthProfileCandidateIds?: string[] }, + ) => ({ + ...store, + profiles: Object.fromEntries( + (plan.forwardedAuthProfileCandidateIds ?? []).flatMap((profileId) => { + const profile = store.profiles[profileId]; + return profile ? [[profileId, profile]] : []; + }), + ), + }), +})); vi.mock("./thinking-runtime.js", () => ({ resolveEffectiveAgentRuntime: mocks.resolveEffectiveAgentRuntime, })); @@ -100,7 +127,10 @@ function request() { beforeEach(() => { vi.clearAllMocks(); mocks.acquireAgentRunPreparedModelRuntime.mockResolvedValue({ - snapshot: { pluginRegistry: createEmptyPluginRegistry() }, + snapshot: { + pluginRegistry: createEmptyPluginRegistry(), + createStores: () => ({ modelRegistry: {} }), + }, release: vi.fn(), }); mocks.isCliRuntimeAliasForProvider.mockReturnValue(false); @@ -111,9 +141,369 @@ beforeEach(() => { auth: { apiKey: "secret", source: "profile:openai:test", mode: "oauth" }, sourceAuthFingerprint: "fingerprint", }); + mocks.resolveModelWithRegistry.mockReturnValue({ + provider: "openai", + id: "gpt-test", + api: "openai-chatgpt-responses", + }); + mocks.ensureAuthProfileStore.mockReturnValue({ version: 1, profiles: {} }); + const plan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + modelRoute: { authRequirement: "subscription" }, + }; + mocks.prepareAgentRuntimeAuth.mockReturnValue({ + plan, + attempts: [{ kind: "implicit", plan }], + }); }); describe("runIsolatedCompletion", () => { + it("hands harness-owned authorization to the V2 owner without resolving a host key", async () => { + const runIsolatedCompletionV2 = vi.fn(async () => ({ + assistant: assistant([{ type: "text", text: "native result" }]), + })); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await expect(runIsolatedCompletion(request())).resolves.toMatchObject({ + text: "native result", + owner: { kind: "harness", id: "codex" }, + }); + expect(mocks.prepareSimpleCompletionModel).not.toHaveBeenCalled(); + expect(runIsolatedCompletionV2).toHaveBeenCalledWith( + expect.objectContaining({ + authorization: expect.objectContaining({ owner: "harness" }), + }), + ); + }); + + it("clamps V2 output tokens to the resolved physical model limit", async () => { + mocks.resolveModelWithRegistry.mockReturnValueOnce({ + provider: "openai", + id: "gpt-test", + api: "openai-chatgpt-responses", + maxTokens: 1_024, + }); + const runIsolatedCompletionV2 = vi.fn(async () => ({ + assistant: assistant([{ type: "text", text: "native result" }]), + })); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await runIsolatedCompletion({ + ...request(), + streamParams: { maxTokens: 4_096, temperature: 0.2 }, + }); + + expect(runIsolatedCompletionV2).toHaveBeenCalledWith( + expect.objectContaining({ streamParams: { maxTokens: 1_024, temperature: 0.2 } }), + ); + }); + + it("keeps automatic harness fallback core-owned and scopes one profile per call", async () => { + const firstPlan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + forwardedAuthProfileId: "openai:first", + forwardedAuthProfileSource: "auto" as const, + forwardedAuthProfileCandidateIds: ["openai:first", "openai:backup"], + modelRoute: { authRequirement: "subscription" as const }, + }; + const backupPlan = { + ...firstPlan, + forwardedAuthProfileId: "openai:backup", + forwardedAuthProfileCandidateIds: ["openai:backup"], + }; + mocks.ensureAuthProfileStore.mockReturnValueOnce({ + version: 1, + profiles: { + "openai:first": { type: "token", provider: "openai", token: "first" }, + "openai:backup": { type: "token", provider: "openai", token: "backup" }, + }, + }); + mocks.prepareAgentRuntimeAuth.mockReturnValueOnce({ + plan: firstPlan, + attempts: [ + { kind: "profile", plan: firstPlan, profileId: "openai:first" }, + { kind: "profile", plan: backupPlan, profileId: "openai:backup" }, + ], + }); + const runIsolatedCompletionV2 = vi + .fn() + .mockRejectedValueOnce(new Error("first profile unavailable")) + .mockResolvedValueOnce({ + assistant: assistant([{ type: "text", text: "backup result" }]), + }); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await expect(runIsolatedCompletion(request())).resolves.toMatchObject({ + text: "backup result", + }); + expect(runIsolatedCompletionV2).toHaveBeenCalledTimes(2); + expect( + runIsolatedCompletionV2.mock.calls.map(([params]) => ({ + profileId: + params.authorization.owner === "harness" + ? params.authorization.plan.forwardedAuthProfileId + : undefined, + candidateIds: + params.authorization.owner === "harness" + ? params.authorization.plan.forwardedAuthProfileCandidateIds + : undefined, + profiles: + params.authorization.owner === "harness" + ? Object.keys(params.authorization.authProfileStore.profiles) + : [], + })), + ).toEqual([ + { + profileId: "openai:first", + candidateIds: ["openai:first"], + profiles: ["openai:first"], + }, + { + profileId: "openai:backup", + candidateIds: ["openai:backup"], + profiles: ["openai:backup"], + }, + ]); + expect(mocks.prepareSimpleCompletionModel).not.toHaveBeenCalled(); + }); + + it("does not unlock direct auth when a prepared profile becomes cooldown-blocked", async () => { + const profilePlan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + forwardedAuthProfileId: "openai:first", + forwardedAuthProfileSource: "auto" as const, + forwardedAuthProfileCandidateIds: ["openai:first"], + modelRoute: { authRequirement: "subscription" as const }, + }; + const directPlan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + modelRoute: { authRequirement: "api-key" as const }, + }; + mocks.ensureAuthProfileStore.mockReturnValueOnce({ + version: 1, + profiles: { + "openai:first": { type: "token", provider: "openai", token: "first" }, + }, + usageStats: { + "openai:first": { cooldownUntil: Date.now() + 60_000 }, + }, + }); + mocks.prepareAgentRuntimeAuth.mockReturnValueOnce({ + plan: profilePlan, + attempts: [ + { kind: "profile", plan: profilePlan, profileId: "openai:first" }, + { + kind: "direct", + plan: directPlan, + allowAuthProfileFallback: false, + requiresPriorProfileAttempt: true, + }, + ], + }); + const runIsolatedCompletionV2 = vi + .fn() + .mockRejectedValueOnce(new Error("profile unavailable")) + .mockResolvedValueOnce({ assistant: assistant([{ type: "text", text: "direct result" }]) }); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await expect(runIsolatedCompletion(request())).rejects.toThrow("temporarily unavailable"); + expect(runIsolatedCompletionV2).not.toHaveBeenCalled(); + expect(mocks.prepareSimpleCompletionModel).not.toHaveBeenCalled(); + }); + + it("skips a cooled profile without hiding a prepared healthy backup", async () => { + const firstPlan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + forwardedAuthProfileId: "openai:first", + forwardedAuthProfileSource: "auto" as const, + forwardedAuthProfileCandidateIds: ["openai:first", "openai:backup"], + modelRoute: { authRequirement: "subscription" as const }, + }; + const backupPlan = { + ...firstPlan, + forwardedAuthProfileId: "openai:backup", + forwardedAuthProfileCandidateIds: ["openai:backup"], + }; + mocks.ensureAuthProfileStore.mockReturnValueOnce({ + version: 1, + profiles: { + "openai:first": { type: "token", provider: "openai", token: "first" }, + "openai:backup": { type: "token", provider: "openai", token: "backup" }, + }, + usageStats: { + "openai:first": { cooldownUntil: Date.now() + 60_000 }, + }, + }); + mocks.prepareAgentRuntimeAuth.mockReturnValueOnce({ + plan: firstPlan, + attempts: [ + { kind: "profile", plan: firstPlan, profileId: "openai:first" }, + { kind: "profile", plan: backupPlan, profileId: "openai:backup" }, + ], + }); + const runIsolatedCompletionV2 = vi.fn(async () => ({ + assistant: assistant([{ type: "text", text: "backup result" }]), + })); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await expect(runIsolatedCompletion(request())).resolves.toMatchObject({ + text: "backup result", + }); + expect(runIsolatedCompletionV2).toHaveBeenCalledOnce(); + expect(runIsolatedCompletionV2).toHaveBeenCalledWith( + expect.objectContaining({ + authorization: expect.objectContaining({ + owner: "harness", + plan: expect.objectContaining({ forwardedAuthProfileId: "openai:backup" }), + }), + }), + ); + }); + + it("allows direct auth after a prepared profile was actually dispatched", async () => { + const profilePlan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + forwardedAuthProfileId: "openai:first", + forwardedAuthProfileSource: "auto" as const, + forwardedAuthProfileCandidateIds: ["openai:first"], + modelRoute: { authRequirement: "subscription" as const }, + }; + const directPlan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + modelRoute: { authRequirement: "api-key" as const }, + }; + mocks.ensureAuthProfileStore.mockReturnValueOnce({ + version: 1, + profiles: { + "openai:first": { type: "token", provider: "openai", token: "first" }, + }, + }); + mocks.prepareAgentRuntimeAuth.mockReturnValueOnce({ + plan: profilePlan, + attempts: [ + { kind: "profile", plan: profilePlan, profileId: "openai:first" }, + { + kind: "direct", + plan: directPlan, + allowAuthProfileFallback: false, + requiresPriorProfileAttempt: true, + }, + ], + }); + const runIsolatedCompletionV2 = vi + .fn() + .mockRejectedValueOnce(new Error("profile unavailable")) + .mockResolvedValueOnce({ assistant: assistant([{ type: "text", text: "direct result" }]) }); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await expect(runIsolatedCompletion(request())).resolves.toMatchObject({ + text: "direct result", + }); + expect(runIsolatedCompletionV2).toHaveBeenCalledTimes(2); + expect(mocks.prepareSimpleCompletionModel).toHaveBeenCalledOnce(); + }); + + it("uses host authorization for V2 API-key routes", async () => { + const plan = { + providerForAuth: "openai", + modelId: "gpt-test", + harnessAuthProvider: "openai", + modelRoute: { authRequirement: "api-key" as const }, + }; + mocks.prepareAgentRuntimeAuth.mockReturnValueOnce({ + plan, + attempts: [{ kind: "implicit", plan }], + }); + const runIsolatedCompletionV2 = vi.fn(async () => ({ + assistant: assistant([{ type: "text", text: "key result" }]), + })); + mocks.getRegisteredAgentHarness.mockReturnValue({ + harness: { + id: "codex", + label: "Codex", + authBootstrap: "harness", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + runIsolatedCompletionV2, + } satisfies AgentHarness, + }); + + await runIsolatedCompletion(request()); + + expect(mocks.prepareSimpleCompletionModel).toHaveBeenCalledOnce(); + expect(runIsolatedCompletionV2).toHaveBeenCalledWith( + expect.objectContaining({ authorization: expect.objectContaining({ owner: "host" }) }), + ); + }); + it("passes one prepared route to the selected harness and returns text", async () => { const runIsolatedCompletionHarness = vi.fn(async () => ({ assistant: assistant([{ type: "text", text: '{"ok":true}' }]), diff --git a/src/agents/isolated-completion.ts b/src/agents/isolated-completion.ts index 28f5bdece7fd..340f515d9fd5 100644 --- a/src/agents/isolated-completion.ts +++ b/src/agents/isolated-completion.ts @@ -18,9 +18,16 @@ import { resolveAgentDir, resolveAgentWorkspaceDir, resolveDefaultAgentId } from import { resolveCliBackendConfig, resolveCliRuntimeCanonicalProvider } from "./cli-backends.js"; import { normalizeCliModel } from "./cli-runner/helpers.js"; import { resolveEmbeddedCliBackendDispatchEligibility } from "./embedded-agent-runner/cli-backend-dispatch-eligibility.js"; +import { resolveModelWithRegistry } from "./embedded-agent-runner/model.js"; import { getRegisteredAgentHarness } from "./harness/registry.js"; import { ensureSelectedAgentHarnessPlugin } from "./harness/runtime-plugin.js"; -import type { AgentHarness } from "./harness/types.js"; +import type { + AgentHarness, + AgentHarnessIsolatedCompletionAuthorization, + AgentHarnessIsolatedCompletionParamsV2, + AgentHarnessIsolatedCompletionResult, +} from "./harness/types.js"; +import { ensureAuthProfileStore } from "./model-auth.js"; import { isCliRuntimeAliasForProvider, resolveCliRuntimeExecutionProvider, @@ -30,6 +37,13 @@ import { unwrapModelHeaderSentinelsForProviderEgress, unwrapSecretSentinelsForProviderEgress, } from "./provider-secret-egress.js"; +import { + canRunPreparedAgentRuntimeAuthAttempt, + prepareAgentRuntimeAuth, + preparedAgentRuntimeProfileAttemptHasCandidate, + type PreparedAgentRuntimeAuthAttempt, +} from "./runtime-plan/prepare-auth.js"; +import { scopeAuthProfileStoreToPreparedPlan } from "./runtime-plan/resolve-auth.js"; import { prepareSimpleCompletionModel } from "./simple-completion-runtime.js"; import { resolveEffectiveAgentRuntime } from "./thinking-runtime.js"; import type { UsageLike } from "./usage.js"; @@ -41,6 +55,7 @@ type RunIsolatedCompletionParams = { /** Explicit credential owner. CLI and harness paths must not replace it with another profile. */ authProfileId?: string; agentId?: string; + agentDir?: string; workspaceDir?: string; /** Concrete owner already resolved by the caller, when available. */ agentHarnessRuntimeOverride?: string; @@ -84,6 +99,29 @@ type AgentHarnessIsolatedCompletionParams = Parameters< NonNullable >[0]; +function clampIsolatedStreamParams( + streamParams: RunIsolatedCompletionParams["streamParams"], + modelMaxTokens: number | undefined, +): RunIsolatedCompletionParams["streamParams"] { + if (streamParams?.maxTokens === undefined || modelMaxTokens === undefined) { + return streamParams; + } + return { ...streamParams, maxTokens: Math.min(streamParams.maxTokens, modelMaxTokens) }; +} + +function selectIsolatedHarnessAuthPlan(attempt: PreparedAgentRuntimeAuthAttempt) { + if (attempt.kind !== "profile") { + return attempt.plan; + } + return { + ...attempt.plan, + forwardedAuthProfileId: attempt.profileId, + // Core owns candidate order. A harness receives one selected credential + // snapshot per call so it cannot inspect or reorder fallback profiles. + forwardedAuthProfileCandidateIds: [attempt.profileId], + }; +} + function requireIsolatedAssistantText(assistant: AssistantMessage): string { if (assistant.stopReason !== "stop" && assistant.stopReason !== "length") { throw new IsolatedCompletionError( @@ -325,13 +363,71 @@ function prepareIsolatedHarnessParams( }; } +function prepareIsolatedHarnessParamsV2( + harness: AgentHarness, + params: AgentHarnessIsolatedCompletionParamsV2, +): AgentHarnessIsolatedCompletionParamsV2 { + if (harness.id === "openclaw" || params.authorization.owner === "harness") { + return params; + } + const boundary = "plugin harness isolated completion handoff"; + const apiKey = params.authorization.auth.apiKey + ? unwrapSecretSentinelsForProviderEgress(params.authorization.auth.apiKey, boundary) + : params.authorization.auth.apiKey; + const model = unwrapModelHeaderSentinelsForProviderEgress(params.authorization.model, boundary); + if (apiKey === params.authorization.auth.apiKey && model === params.authorization.model) { + return params; + } + return { + ...params, + authorization: { + ...params.authorization, + model, + auth: { ...params.authorization.auth, apiKey }, + }, + }; +} + +async function prepareHostAuthorization(params: { + config: OpenClawConfig; + agentId: string; + agentDir: string; + provider: string; + modelId: string; + authProfileId?: string; +}): Promise> { + const prepared = await prepareSimpleCompletionModel({ + cfg: params.config, + agentId: params.agentId, + provider: params.provider, + modelId: params.modelId, + agentDir: params.agentDir, + profileId: params.authProfileId, + allowMissingApiKeyModes: ["aws-sdk"], + allowBundledStaticCatalogFallback: true, + skipAgentDiscovery: true, + bindAuthOwner: true, + }); + if ("error" in prepared) { + throw new Error(`Isolated completion preparation failed: ${prepared.error}`); + } + return { + owner: "host", + model: prepared.model, + auth: prepared.auth, + ...(prepared.sourceAuthFingerprint + ? { sourceAuthFingerprint: prepared.sourceAuthFingerprint } + : {}), + }; +} + /** Run one fresh completion without any model-callable tool surface or fallback. */ export async function runIsolatedCompletion( request: RunIsolatedCompletionParams, ): Promise { const config = request.config ?? {}; const agentId = request.agentId ?? resolveDefaultAgentId(config); - const agentDir = resolveAgentDir(config, agentId); + const agentDir = request.agentDir ?? resolveAgentDir(config, agentId); const workspaceDir = request.workspaceDir ?? resolveAgentWorkspaceDir(config, agentId); const provider = resolveCliRuntimeCanonicalProvider({ @@ -398,35 +494,15 @@ export async function runIsolatedCompletion( } const harness = await resolveHarness(runtime); - if (!harness.runIsolatedCompletion) { + if (!harness.runIsolatedCompletionV2 && !harness.runIsolatedCompletion) { throw new IsolatedCompletionError( "unsupported", `Agent harness ${harness.id} does not support isolated completion.`, ); } - const prepared = await prepareSimpleCompletionModel({ - cfg: config, - agentId, + const commonParams = { provider, modelId: request.model, - agentDir, - profileId: request.authProfileId, - allowMissingApiKeyModes: ["aws-sdk"], - allowBundledStaticCatalogFallback: true, - skipAgentDiscovery: true, - bindAuthOwner: true, - }); - if ("error" in prepared) { - throw new Error(`Isolated completion preparation failed: ${prepared.error}`); - } - const harnessParams: AgentHarnessIsolatedCompletionParams = { - provider, - modelId: request.model, - model: prepared.model, - auth: prepared.auth, - ...(prepared.sourceAuthFingerprint - ? { sourceAuthFingerprint: prepared.sourceAuthFingerprint } - : {}), config, agentId, agentDir, @@ -436,11 +512,164 @@ export async function runIsolatedCompletion( timeoutMs: request.timeoutMs, abortSignal: request.abortSignal, thinkLevel: request.thinkLevel, - streamParams: request.streamParams, }; - const result = await harness.runIsolatedCompletion( - prepareIsolatedHarnessParams(harness, harnessParams), - ); + let result: AgentHarnessIsolatedCompletionResult | undefined; + if (harness.runIsolatedCompletionV2) { + let modelMaxTokens: number | undefined; + let authProfileStore: ReturnType | undefined; + let authAttempts: readonly PreparedAgentRuntimeAuthAttempt[] | undefined; + if (harness.authBootstrap === "harness") { + const { modelRegistry } = lease.snapshot.createStores(); + const runtimeModel = resolveModelWithRegistry({ + provider, + modelId: request.model, + modelRegistry, + cfg: config, + }); + if (!runtimeModel) { + throw new IsolatedCompletionError( + "runtime-unavailable", + `Unknown isolated completion model ${provider}/${request.model}.`, + ); + } + modelMaxTokens = runtimeModel.maxTokens; + authProfileStore = ensureAuthProfileStore(agentDir, { + readOnly: true, + allowKeychainPrompt: false, + config, + }); + authAttempts = prepareAgentRuntimeAuth({ + provider: runtimeModel.provider, + modelId: runtimeModel.id, + modelApi: runtimeModel.api, + modelBaseUrl: runtimeModel.baseUrl, + config, + env: process.env, + agentDir, + workspaceDir, + authProfileStore, + sessionAuthProfileId: request.authProfileId, + sessionAuthProfileSource: request.authProfileId ? "user" : undefined, + harnessId: harness.id, + harnessRuntime: harness.id, + harnessAuthBootstrap: harness.authBootstrap, + }).attempts; + } + let firstError: unknown; + let priorProfileAttempted = false; + for (const preparedAttempt of authAttempts?.length ? authAttempts : [undefined]) { + const attempt: PreparedAgentRuntimeAuthAttempt | undefined = + preparedAttempt?.kind === "profile" + ? { ...preparedAttempt, plan: selectIsolatedHarnessAuthPlan(preparedAttempt) } + : preparedAttempt; + if ( + attempt && + !canRunPreparedAgentRuntimeAuthAttempt({ attempt, priorProfileAttempted }) + ) { + firstError ??= new Error("Prepared direct auth requires a prior profile attempt."); + continue; + } + if ( + attempt?.kind === "profile" && + authProfileStore && + !preparedAgentRuntimeProfileAttemptHasCandidate({ + attempt, + store: authProfileStore, + modelId: request.model, + }) + ) { + firstError ??= new Error( + "Prepared runtime auth candidates are temporarily unavailable.", + ); + continue; + } + try { + let authorization: AgentHarnessIsolatedCompletionAuthorization; + if ( + attempt?.plan.harnessAuthProvider && + attempt.plan.modelRoute?.authRequirement !== "api-key" && + authProfileStore + ) { + const plan = attempt.plan; + authorization = { + owner: "harness", + plan, + authProfileStore: scopeAuthProfileStoreToPreparedPlan(authProfileStore, plan), + }; + } else { + authorization = await prepareHostAuthorization({ + config, + agentId, + agentDir, + provider, + modelId: request.model, + authProfileId: + attempt?.kind === "profile" ? attempt.profileId : request.authProfileId, + }); + modelMaxTokens = authorization.model.maxTokens; + } + if ( + attempt?.kind === "profile" && + authProfileStore && + !preparedAgentRuntimeProfileAttemptHasCandidate({ + attempt, + store: authProfileStore, + modelId: request.model, + }) + ) { + throw new Error("Prepared runtime auth candidates are temporarily unavailable."); + } + const pending = harness.runIsolatedCompletionV2( + prepareIsolatedHarnessParamsV2(harness, { + ...commonParams, + authorization, + streamParams: clampIsolatedStreamParams(request.streamParams, modelMaxTokens), + }), + ); + priorProfileAttempted ||= attempt?.kind === "profile"; + result = await pending; + break; + } catch (error) { + if (request.abortSignal?.aborted) { + throw error; + } + firstError ??= error; + } + } + if (!result) { + if (firstError instanceof Error) { + throw firstError; + } + throw new Error("No prepared auth attempt succeeded.", { cause: firstError }); + } + } else { + const authorization = await prepareHostAuthorization({ + config, + agentId, + agentDir, + provider, + modelId: request.model, + authProfileId: request.authProfileId, + }); + const harnessParams: AgentHarnessIsolatedCompletionParams = { + ...commonParams, + streamParams: clampIsolatedStreamParams( + request.streamParams, + authorization.model.maxTokens, + ), + model: authorization.model, + auth: authorization.auth, + ...(authorization.sourceAuthFingerprint + ? { sourceAuthFingerprint: authorization.sourceAuthFingerprint } + : {}), + }; + result = await harness.runIsolatedCompletion!( + prepareIsolatedHarnessParams(harness, harnessParams), + ); + } + if (!result) { + throw new IsolatedCompletionError("runtime-unavailable", "Isolated completion failed."); + } return { text: requireIsolatedAssistantText(result.assistant), provider: result.assistant.provider, diff --git a/src/auto-reply/reply/conversation-label-generator.test.ts b/src/auto-reply/reply/conversation-label-generator.test.ts index f23628091396..24f585e77c34 100644 --- a/src/auto-reply/reply/conversation-label-generator.test.ts +++ b/src/auto-reply/reply/conversation-label-generator.test.ts @@ -1,330 +1,140 @@ /** Tests generated conversation labels for reply sessions. */ -import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { beforeEach, describe, expect, it, vi } from "vitest"; -const completeWithPreparedSimpleCompletionModel = vi.hoisted(() => vi.fn()); -const logVerbose = vi.hoisted(() => vi.fn()); -const prepareSimpleCompletionModelForAgent = vi.hoisted(() => vi.fn()); +const runIsolatedCompletion = vi.hoisted(() => vi.fn()); const resolveSimpleCompletionSelectionForAgent = vi.hoisted(() => vi.fn()); +vi.mock("../../agents/isolated-completion.js", () => ({ runIsolatedCompletion })); vi.mock("../../agents/simple-completion-runtime.js", () => ({ - completeWithPreparedSimpleCompletionModel, - prepareSimpleCompletionModelForAgent, resolveSimpleCompletionSelectionForAgent, })); -vi.mock("../../globals.js", () => ({ logVerbose })); - import { generateConversationLabel, generateConversationLabelWithFallback, } from "./conversation-label-generator.js"; -function firstCompletionArgs() { - const call = completeWithPreparedSimpleCompletionModel.mock.calls.at(0); - if (!call) { - throw new Error("expected simple completion call"); - } - return call[0]; +function resolveSelection({ modelRef, useUtilityModel, agentDir }: Record) { + const ref = + typeof modelRef === "string" + ? modelRef + : useUtilityModel + ? "openai/gpt-mini@work" + : "openai/gpt-main@work"; + const [rawModel, profileId] = ref.split("@"); + const model = rawModel ?? ""; + const slash = model.indexOf("/"); + return { + provider: model.slice(0, slash), + modelId: model.slice(slash + 1), + profileId, + agentDir: typeof agentDir === "string" ? agentDir : "/tmp/openclaw-agent", + }; } describe("generateConversationLabel", () => { beforeEach(() => { - completeWithPreparedSimpleCompletionModel.mockReset(); - logVerbose.mockReset(); - prepareSimpleCompletionModelForAgent.mockReset(); - - prepareSimpleCompletionModelForAgent.mockResolvedValue({ - selection: { - provider: "openai", - modelId: "gpt-test", - agentDir: "/tmp/openclaw-agent", - }, - model: { provider: "openai", id: "gpt-test", maxTokens: 8192 }, - auth: { apiKey: "resolved-key", mode: "api-key" }, - }); - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [{ type: "text", text: "Topic label" }], - }); + runIsolatedCompletion.mockReset(); + resolveSimpleCompletionSelectionForAgent.mockReset(); + resolveSimpleCompletionSelectionForAgent.mockImplementation(resolveSelection); + runIsolatedCompletion.mockResolvedValue({ text: "Topic label" }); }); - afterEach(() => { - vi.useRealTimers(); - }); - - it("prepares the configured utility model in the routed agent directory", async () => { - const cfg = { agents: { defaults: { utilityModel: "openai/gpt-test" } } }; - - await generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "prompt", - cfg, - agentId: "billing", - agentDir: "/tmp/agents/billing/agent", - }); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledWith({ - cfg, - agentId: "billing", - agentDir: "/tmp/agents/billing/agent", - useUtilityModel: true, - useAsyncModelResolution: true, - allowMissingApiKeyModes: ["aws-sdk"], - }); - }); - - it("passes the label prompt and a reasoning-safe bounded completion budget", async () => { - vi.useFakeTimers(); - vi.setSystemTime(1_710_000_000_000); - const cfg = {}; - - await generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg, - }); - - expect(firstCompletionArgs()).toMatchObject({ - model: { provider: "openai", id: "gpt-test" }, - auth: { apiKey: "resolved-key", mode: "api-key" }, - cfg, - context: { - systemPrompt: "Generate a label", - messages: [ - { - role: "user", - content: "Need help with invoices", - timestamp: 1_710_000_000_000, - }, - ], - }, - options: { - maxTokens: 4_096, - temperature: 0.3, - }, - }); - expect(firstCompletionArgs().options.signal).toBeInstanceOf(AbortSignal); - }); - - it("caps the completion budget at the model output limit", async () => { - prepareSimpleCompletionModelForAgent.mockResolvedValue({ - selection: { - provider: "openai", - modelId: "gpt-test", - agentDir: "/tmp/openclaw-agent", - }, - model: { provider: "openai", id: "gpt-test", maxTokens: 1_024 }, - auth: { apiKey: "resolved-key", mode: "api-key" }, - }); - - await generateConversationLabel({ - userMessage: "test topic creation", - prompt: "Generate a label", - cfg: {}, - }); - - expect(firstCompletionArgs().options.maxTokens).toBe(1_024); - }); - - it("omits temperature for Codex Responses simple completions", async () => { - prepareSimpleCompletionModelForAgent.mockResolvedValue({ - selection: { - provider: "openai", - modelId: "gpt-5.5", - agentDir: "/tmp/openclaw-agent", - }, - model: { - provider: "openai", - id: "gpt-5.5", - api: "openai-chatgpt-responses", - maxTokens: 8192, - }, - auth: { apiKey: "resolved-key", mode: "api-key" }, - }); - - await generateConversationLabel({ - userMessage: "test topic creation", - prompt: "Generate a label", - cfg: {}, - }); - - expect(firstCompletionArgs().options).not.toHaveProperty("temperature"); - }); - - it("returns null when utility model preparation fails", async () => { - prepareSimpleCompletionModelForAgent.mockResolvedValue({ - error: 'No API key resolved for provider "openai".', - }); + it("routes the utility model through isolated completion with the selected auth owner", async () => { + const cfg = { agents: { defaults: { utilityModel: "openai/gpt-mini" } } }; await expect( generateConversationLabel({ userMessage: "Need help with invoices", prompt: "Generate a label", - cfg: {}, - }), - ).resolves.toBeNull(); - - expect(logVerbose).toHaveBeenCalledWith( - 'conversation-label-generator: No API key resolved for provider "openai".', - ); - expect(completeWithPreparedSimpleCompletionModel).not.toHaveBeenCalled(); - }); - - it("falls back to the primary model when utility model preparation fails", async () => { - prepareSimpleCompletionModelForAgent - .mockResolvedValueOnce({ - error: 'No API key resolved for provider "openai".', - selection: { - provider: "openai", - modelId: "gpt-5.6-luna", - agentDir: "/tmp/openclaw-agent", - }, - }) - .mockResolvedValueOnce({ - selection: { - provider: "openai", - modelId: "gpt-5.6-sol", - agentDir: "/tmp/openclaw-agent", - }, - model: { provider: "openai", id: "gpt-5.6-sol", maxTokens: 8192 }, - auth: { apiKey: "test-api-key", mode: "api-key" }, - }); - - await expect( - generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg: {}, + cfg, + agentId: "billing", + agentDir: "/tmp/agents/billing/agent", }), ).resolves.toBe("Topic label"); - expect(prepareSimpleCompletionModelForAgent).toHaveBeenNthCalledWith( - 2, - expect.objectContaining({ useUtilityModel: false }), - ); - expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledOnce(); + expect(runIsolatedCompletion).toHaveBeenCalledWith({ + config: cfg, + provider: "openai", + model: "gpt-mini", + authProfileId: "work", + agentId: "billing", + agentDir: "/tmp/agents/billing/agent", + systemPrompt: "Generate a label", + prompt: "Need help with invoices", + timeoutMs: 15_000, + streamParams: { maxTokens: 4_096 }, + }); }); - it("falls back to the primary model when the utility completion fails", async () => { - prepareSimpleCompletionModelForAgent - .mockResolvedValueOnce({ - selection: { - provider: "openai", - modelId: "gpt-5.6-luna", - agentDir: "/tmp/openclaw-agent", - }, - model: { provider: "openai", id: "gpt-5.6-luna", maxTokens: 8192 }, - auth: { apiKey: "test-api-key", mode: "oauth" }, - }) - .mockResolvedValueOnce({ - selection: { - provider: "openai", - modelId: "gpt-5.6-sol", - agentDir: "/tmp/openclaw-agent", - }, - model: { provider: "openai", id: "gpt-5.6-sol", maxTokens: 8192 }, - auth: { apiKey: "test-api-key", mode: "oauth" }, - }); - completeWithPreparedSimpleCompletionModel - .mockResolvedValueOnce({ - content: [], - stopReason: "error", - errorMessage: "utility unavailable", - }) - .mockResolvedValueOnce({ content: [{ type: "text", text: "Primary title" }] }); + it("uses one explicit model and timeout when supplied", async () => { + await generateConversationLabel({ + userMessage: "Message", + prompt: "Prompt", + cfg: {}, + modelRef: "anthropic/claude-haiku@team", + timeoutMs: 900, + }); + + expect(runIsolatedCompletion).toHaveBeenCalledOnce(); + expect(runIsolatedCompletion).toHaveBeenCalledWith( + expect.objectContaining({ + provider: "anthropic", + model: "claude-haiku", + authProfileId: "team", + timeoutMs: 900, + }), + ); + }); + + it("falls back to the primary after a utility failure", async () => { + runIsolatedCompletion + .mockRejectedValueOnce(new Error("utility unavailable")) + .mockResolvedValueOnce({ text: "Primary title" }); await expect( - generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg: {}, - }), + generateConversationLabel({ userMessage: "Message", prompt: "Prompt", cfg: {} }), ).resolves.toBe("Primary title"); - expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledTimes(2); + expect(runIsolatedCompletion).toHaveBeenCalledTimes(2); + expect(runIsolatedCompletion.mock.calls[1]?.[0]?.model).toBe("gpt-main"); }); - it("does not call the same primary model twice when utility routing resolves to it", async () => { - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [], - stopReason: "error", - errorMessage: "primary unavailable", - }); + it("throws a sanitized error after every configured attempt fails", async () => { + runIsolatedCompletion.mockRejectedValue(new Error("secret-bearing provider failure")); await expect( - generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg: {}, - }), + generateConversationLabel({ userMessage: "Message", prompt: "Prompt", cfg: {} }), + ).rejects.toThrow("conversation label generation failed (utility, primary fallback)"); + }); + + it("deduplicates utility and primary when they resolve to the same owner", async () => { + resolveSimpleCompletionSelectionForAgent.mockReturnValue({ + provider: "openai", + modelId: "same-model", + profileId: "work", + agentDir: "/tmp/openclaw-agent", + }); + runIsolatedCompletion.mockResolvedValue({ text: "" }); + + await expect( + generateConversationLabel({ userMessage: "Message", prompt: "Prompt", cfg: {} }), ).resolves.toBeNull(); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledTimes(2); - expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledOnce(); + expect(runIsolatedCompletion).toHaveBeenCalledOnce(); }); - it("logs completion errors instead of treating them as empty labels", async () => { - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [], - stopReason: "error", - errorMessage: "Codex error: Instructions are required", - }); - - const label = await generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg: {}, - }); - - expect(label).toBeNull(); - expect(logVerbose).toHaveBeenCalledWith( - "conversation-label-generator: completion failed: Codex error: Instructions are required", - ); - }); - - it("bounds the generated label length", async () => { - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [{ type: "text", text: "A very long generated topic label" }], - }); + it("bounds labels without splitting surrogate pairs", async () => { + runIsolatedCompletion.mockResolvedValue({ text: `${"a".repeat(11)}😀tail` }); await expect( generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg: {}, - maxLength: 12, - }), - ).resolves.toBe("A very long "); - }); - - it("drops a split emoji instead of returning a lone surrogate", async () => { - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [{ type: "text", text: `${"a".repeat(11)}😀tail` }], - }); - - await expect( - generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", + userMessage: "Message", + prompt: "Prompt", cfg: {}, maxLength: 12, }), ).resolves.toBe("a".repeat(11)); }); - - it("returns null when the length cap cannot retain the first emoji", async () => { - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [{ type: "text", text: "😀 label" }], - }); - - await expect( - generateConversationLabel({ - userMessage: "Need help with invoices", - prompt: "Generate a label", - cfg: {}, - maxLength: 1, - }), - ).resolves.toBeNull(); - }); }); describe("generateConversationLabelWithFallback", () => { @@ -339,292 +149,78 @@ describe("generateConversationLabelWithFallback", () => { }; beforeEach(() => { - completeWithPreparedSimpleCompletionModel.mockReset(); - logVerbose.mockReset(); - prepareSimpleCompletionModelForAgent.mockReset(); + runIsolatedCompletion.mockReset(); resolveSimpleCompletionSelectionForAgent.mockReset(); - resolveSimpleCompletionSelectionForAgent.mockImplementation(({ modelRef }) => { - const [model, profileId] = modelRef.split("@"); - const slash = model.indexOf("/"); - return { - provider: model.slice(0, slash), - modelId: model.slice(slash + 1), - profileId, - agentDir: "/tmp/openclaw-agent", - }; - }); - prepareSimpleCompletionModelForAgent.mockImplementation(async ({ modelRef }) => { - const [model] = modelRef.split("@"); - const slash = model.indexOf("/"); - return { - selection: { - provider: model.slice(0, slash), - modelId: model.slice(slash + 1), - profileId: "work", - agentDir: "/tmp/openclaw-agent", - }, - model: { - provider: model.slice(0, slash), - id: model.slice(slash + 1), - maxTokens: 8192, - }, - auth: { apiKey: "resolved-key", mode: "api-key" }, - }; - }); - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ - content: [{ type: "text", text: "Utility title" }], - }); + resolveSimpleCompletionSelectionForAgent.mockImplementation(resolveSelection); + runIsolatedCompletion.mockResolvedValue({ text: "Utility title" }); }); - afterEach(() => { - vi.useRealTimers(); - }); - - it("uses the utility candidate once with the selected auth owner", async () => { + it("uses the utility candidate once", async () => { await expect(generateConversationLabelWithFallback(params)).resolves.toBe("Utility title"); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledOnce(); - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledWith({ - cfg: {}, - agentId: "billing", - agentDir: undefined, - modelRef: "openai/gpt-mini@work", - bindAuthOwner: true, - useAsyncModelResolution: true, - allowMissingApiKeyModes: ["aws-sdk"], + expect(runIsolatedCompletion).toHaveBeenCalledOnce(); + expect(runIsolatedCompletion.mock.calls[0]?.[0]).toMatchObject({ + provider: "openai", + model: "gpt-mini", + authProfileId: "work", }); }); it("locks an inherited profile onto a same-provider utility ref", async () => { - await expect( - generateConversationLabelWithFallback({ - ...params, - utilityModelRef: "openai/gpt-mini", - }), - ).resolves.toBe("Utility title"); + await generateConversationLabelWithFallback({ ...params, utilityModelRef: "openai/gpt-mini" }); - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).toMatchObject({ - modelRef: "openai/gpt-mini@work", - bindAuthOwner: true, - }); - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).not.toHaveProperty( - "preferredProfile", + expect(resolveSimpleCompletionSelectionForAgent).toHaveBeenCalledWith( + expect.objectContaining({ modelRef: "openai/gpt-mini@work" }), ); + expect(runIsolatedCompletion.mock.calls[0]?.[0]?.authProfileId).toBe("work"); }); - it("does not force the regular profile onto a cross-provider utility model", async () => { - await expect( - generateConversationLabelWithFallback({ - ...params, - utilityModelRef: "anthropic/claude-haiku-4-5", - }), - ).resolves.toBe("Utility title"); - - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).toEqual({ - cfg: {}, - agentId: "billing", - agentDir: undefined, - modelRef: "anthropic/claude-haiku-4-5", - bindAuthOwner: true, - useAsyncModelResolution: true, - allowMissingApiKeyModes: ["aws-sdk"], - }); - }); - - it("does not inherit profiles across logical providers sharing one runtime", async () => { - resolveSimpleCompletionSelectionForAgent.mockImplementation(({ modelRef }) => ({ - provider: modelRef.startsWith("anthropic/") ? "anthropic" : "openai", - runtimeProvider: "openai", - modelId: modelRef.split("/").slice(1).join("/"), - agentDir: "/tmp/openclaw-agent", - })); - - await expect( - generateConversationLabelWithFallback({ - ...params, - utilityModelRef: "anthropic/claude-haiku-4-5", - }), - ).resolves.toBe("Utility title"); - - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).not.toHaveProperty( - "preferredProfile", - ); - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]?.modelRef).toBe( - "anthropic/claude-haiku-4-5", - ); - }); - - it("falls back when utility preparation fails", async () => { - prepareSimpleCompletionModelForAgent.mockResolvedValueOnce({ error: "missing auth" }); - completeWithPreparedSimpleCompletionModel.mockResolvedValueOnce({ - content: [{ type: "text", text: "Regular title" }], + it("does not inherit a profile across providers", async () => { + await generateConversationLabelWithFallback({ + ...params, + utilityModelRef: "anthropic/claude-haiku", }); - await expect(generateConversationLabelWithFallback(params)).resolves.toBe("Regular title"); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledTimes(2); - expect(prepareSimpleCompletionModelForAgent.mock.calls[1]?.[0]?.modelRef).toBe( - "openai/gpt-main@work", - ); + expect(runIsolatedCompletion.mock.calls[0]?.[0]).toMatchObject({ + provider: "anthropic", + model: "claude-haiku", + }); + expect(runIsolatedCompletion.mock.calls[0]?.[0]?.authProfileId).toBeUndefined(); }); - it.each([ - { - name: "error stop reason", - first: { content: [], stopReason: "error", errorMessage: "utility failed" }, - }, - { name: "empty output", first: { content: [] } }, - ])("falls back after utility $name", async ({ first }) => { - completeWithPreparedSimpleCompletionModel - .mockResolvedValueOnce(first) - .mockResolvedValueOnce({ content: [{ type: "text", text: "Regular title" }] }); - - await expect(generateConversationLabelWithFallback(params)).resolves.toBe("Regular title"); - - expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledTimes(2); - }); - - it("falls back when utility output fails operation-specific normalization", async () => { - completeWithPreparedSimpleCompletionModel - .mockResolvedValueOnce({ content: [{ type: "text", text: "Title:" }] }) - .mockResolvedValueOnce({ content: [{ type: "text", text: "Regular title" }] }); + it("records an exhausted failure after fallback normalization rejects the result", async () => { + runIsolatedCompletion + .mockRejectedValueOnce(new Error("utility unavailable")) + .mockResolvedValueOnce({ text: "Title:" }); await expect( generateConversationLabelWithFallback({ ...params, normalizeLabel: (label) => (label === "Title:" ? null : label), }), - ).resolves.toBe("Regular title"); + ).rejects.toThrow("conversation label generation failed (utility)"); + expect(runIsolatedCompletion).toHaveBeenCalledTimes(2); }); - it("falls back after a utility completion exception", async () => { - completeWithPreparedSimpleCompletionModel - .mockRejectedValueOnce(new Error("transport failed")) - .mockResolvedValueOnce({ content: [{ type: "text", text: "Regular title" }] }); - - await expect(generateConversationLabelWithFallback(params)).resolves.toBe("Regular title"); - }); - - it("falls back after the utility attempt times out", async () => { - vi.useFakeTimers(); - completeWithPreparedSimpleCompletionModel - .mockImplementationOnce( - ({ options }) => - new Promise((_resolve, reject) => { - options.signal.addEventListener("abort", () => reject(new Error("aborted"))); - }), - ) - .mockResolvedValueOnce({ content: [{ type: "text", text: "Regular title" }] }); - - const generated = generateConversationLabelWithFallback(params); - await vi.advanceTimersByTimeAsync(15_000); - - await expect(generated).resolves.toBe("Regular title"); - }); - - it("returns null when both explicit candidates fail", async () => { - prepareSimpleCompletionModelForAgent - .mockResolvedValueOnce({ error: "utility auth failed" }) - .mockResolvedValueOnce({ error: "regular auth failed" }); - - await expect(generateConversationLabelWithFallback(params)).resolves.toBeNull(); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledTimes(2); - expect(completeWithPreparedSimpleCompletionModel).not.toHaveBeenCalled(); - }); - - it("skips a regular candidate that resolves to the same model and profile", async () => { - resolveSimpleCompletionSelectionForAgent.mockReturnValue({ - provider: "openai", - modelId: "same-model", - profileId: "work", - agentDir: "/tmp/openclaw-agent", - }); - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ content: [] }); - - await expect(generateConversationLabelWithFallback(params)).resolves.toBeNull(); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledOnce(); - expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledOnce(); - }); - - it("deduplicates candidates after asynchronous preparation resolves them identically", async () => { - prepareSimpleCompletionModelForAgent.mockResolvedValue({ - selection: { - provider: "openai", - modelId: "resolved-same-model", - profileId: "work", - agentDir: "/tmp/openclaw-agent", - }, - model: { provider: "openai", id: "resolved-same-model", maxTokens: 8192 }, - auth: { apiKey: "resolved-key", mode: "api-key" }, - }); - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ content: [] }); - - await expect(generateConversationLabelWithFallback(params)).resolves.toBeNull(); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledTimes(2); - expect(completeWithPreparedSimpleCompletionModel).toHaveBeenCalledOnce(); - }); - - it("inherits the regular profile for unresolved same-provider utility refs", async () => { - resolveSimpleCompletionSelectionForAgent.mockReturnValue(null); + it("keeps an explicit runtime owner across utility and primary attempts", async () => { + runIsolatedCompletion + .mockRejectedValueOnce(new Error("utility unavailable")) + .mockResolvedValueOnce({ text: "Primary title" }); await expect( generateConversationLabelWithFallback({ ...params, - utilityModelRef: "openai/gpt-mini", + agentHarnessRuntimeOverride: "codex", }), - ).resolves.toBe("Utility title"); + ).resolves.toBe("Primary title"); - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).toMatchObject({ - modelRef: "openai/gpt-mini@work", - bindAuthOwner: true, - }); - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).not.toHaveProperty( - "preferredProfile", - ); + expect( + runIsolatedCompletion.mock.calls.map(([request]) => request.agentHarnessRuntimeOverride), + ).toEqual(["codex", "codex"]); }); - it("does not inherit the regular profile for unresolved cross-provider utility refs", async () => { - resolveSimpleCompletionSelectionForAgent.mockReturnValue(null); - - await expect( - generateConversationLabelWithFallback({ - ...params, - utilityModelRef: "anthropic/claude-haiku-4-5", - }), - ).resolves.toBe("Utility title"); - - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]).not.toHaveProperty( - "preferredProfile", - ); - }); - - it("deduplicates identical raw refs when selection resolution is unavailable", async () => { - resolveSimpleCompletionSelectionForAgent.mockReturnValue(null); - completeWithPreparedSimpleCompletionModel.mockResolvedValue({ content: [] }); - - await expect( - generateConversationLabelWithFallback({ - ...params, - utilityModelRef: params.regularModelRef, - }), - ).resolves.toBeNull(); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledOnce(); - }); - - it("uses the regular candidate directly when no utility model is available", async () => { + it("uses the regular candidate directly when no utility model exists", async () => { const { utilityModelRef: _utilityModelRef, ...regularOnlyParams } = params; - - await expect(generateConversationLabelWithFallback(regularOnlyParams)).resolves.toBe( - "Utility title", - ); - - expect(prepareSimpleCompletionModelForAgent).toHaveBeenCalledOnce(); - expect(prepareSimpleCompletionModelForAgent.mock.calls[0]?.[0]?.modelRef).toBe( - "openai/gpt-main@work", - ); + await generateConversationLabelWithFallback(regularOnlyParams); + expect(runIsolatedCompletion.mock.calls[0]?.[0]?.model).toBe("gpt-main"); }); }); diff --git a/src/auto-reply/reply/conversation-label-generator.ts b/src/auto-reply/reply/conversation-label-generator.ts index 59d428539b0c..a4e2eb4718f7 100644 --- a/src/auto-reply/reply/conversation-label-generator.ts +++ b/src/auto-reply/reply/conversation-label-generator.ts @@ -1,31 +1,21 @@ // Generates short labels for sessions from conversation context. import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice"; import { resolveDefaultAgentId } from "../../agents/agent-scope.js"; +import { runIsolatedCompletion } from "../../agents/isolated-completion.js"; import { splitTrailingAuthProfile } from "../../agents/model-ref-profile.js"; -import { - completeWithPreparedSimpleCompletionModel, - prepareSimpleCompletionModelForAgent, - resolveSimpleCompletionSelectionForAgent, -} from "../../agents/simple-completion-runtime.js"; +import { resolveSimpleCompletionSelectionForAgent } from "../../agents/simple-completion-runtime.js"; import type { OpenClawConfig } from "../../config/types.openclaw.js"; -import { logVerbose } from "../../globals.js"; -import type { TextContent } from "../../llm/types.js"; const DEFAULT_MAX_LABEL_LENGTH = 128; // Reasoning models spend output tokens before emitting the short visible label. -// A tiny cap can leave no text, so keep the bounded title budget large enough -// for reasoning while respecting models with a lower output limit. const CONVERSATION_LABEL_MAX_TOKENS = 4_096; const TIMEOUT_MS = 15_000; -type PreparedLabelModel = Awaited>; -type ReadyLabelModel = Extract; type LabelModelPhase = "utility" | "primary fallback"; type ConversationLabelAttempt = { modelRef?: string; useUtilityModel?: boolean; preferredProfile?: string; - bindAuthOwner?: boolean; }; /** Inputs for generating a short conversation label from the configured utility model. */ @@ -35,6 +25,9 @@ export type ConversationLabelParams = { cfg: OpenClawConfig; agentId?: string; agentDir?: string; + agentHarnessRuntimeOverride?: string; + modelRef?: string; + timeoutMs?: number; maxLength?: number; }; @@ -45,84 +38,16 @@ type ConversationLabelFallbackParams = ConversationLabelParams & { normalizeLabel?: (label: string) => string | null; }; -function isTextContentBlock(block: { type: string }): block is TextContent { - return block.type === "text"; -} - -function isCodexSimpleCompletionModel(model: { api?: string; provider?: string }): boolean { - return model.api === "openai-chatgpt-responses"; -} - -function extractSimpleCompletionError(result: { - stopReason?: string; - errorMessage?: string; -}): string | null { - if (result.stopReason !== "error") { - return null; - } - return result.errorMessage?.trim() || "unknown error"; -} - function resolveMaxLabelLength(value: number | undefined): number { return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : DEFAULT_MAX_LABEL_LENGTH; } -function logLabelFailure(phase: LabelModelPhase, message: string): void { - const prefix = phase === "utility" ? "" : `${phase} `; - logVerbose(`conversation-label-generator: ${prefix}${message}`); -} - -async function prepareLabelModel(params: { - cfg: OpenClawConfig; - agentId: string; - agentDir?: string; - attempt: ConversationLabelAttempt; - phase: LabelModelPhase; -}): Promise { - try { - const prepared = await prepareSimpleCompletionModelForAgent({ - cfg: params.cfg, - agentId: params.agentId, - agentDir: params.agentDir, - ...(params.attempt.modelRef ? { modelRef: params.attempt.modelRef } : {}), - ...(params.attempt.useUtilityModel !== undefined - ? { useUtilityModel: params.attempt.useUtilityModel } - : {}), - ...(params.attempt.preferredProfile - ? { preferredProfile: params.attempt.preferredProfile } - : {}), - ...(params.attempt.bindAuthOwner !== undefined - ? { bindAuthOwner: params.attempt.bindAuthOwner } - : {}), - useAsyncModelResolution: true, - allowMissingApiKeyModes: ["aws-sdk"], - }); - if ("error" in prepared) { - logLabelFailure(params.phase, prepared.error); - } - return prepared; - } catch (err) { - logLabelFailure(params.phase, `model preparation failed: ${String(err)}`); - return null; - } -} - -function selectedLabelModelsMatch( - first: PreparedLabelModel | null, - second: PreparedLabelModel | null, -): boolean { - const firstSelection = first && "selection" in first ? first.selection : undefined; - const secondSelection = second && "selection" in second ? second.selection : undefined; - return Boolean( - firstSelection && - secondSelection && - firstSelection.provider === secondSelection.provider && - firstSelection.runtimeProvider === secondSelection.runtimeProvider && - firstSelection.modelId === secondSelection.modelId && - firstSelection.profileId === secondSelection.profileId, - ); +function resolveTimeoutMs(value: number | undefined): number { + return typeof value === "number" && Number.isFinite(value) && value > 0 + ? Math.floor(value) + : TIMEOUT_MS; } function resolveAttemptSelection(params: { @@ -170,111 +95,96 @@ function resolveAttemptKey(params: { } async function completeLabel(params: { - prepared: ReadyLabelModel; cfg: OpenClawConfig; + agentId: string; + agentDir?: string; + agentHarnessRuntimeOverride?: string; + attempt: ConversationLabelAttempt; userMessage: string; prompt: string; + timeoutMs: number; maxLength: number; - phase: LabelModelPhase; }): Promise { - const controller = new AbortController(); - const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS); - try { - const maxTokens = Math.min( - CONVERSATION_LABEL_MAX_TOKENS, - Math.floor(params.prepared.model.maxTokens), - ); - // Label generation should never block normal reply handling for long. - const result = await completeWithPreparedSimpleCompletionModel({ - model: params.prepared.model, - auth: params.prepared.auth, - cfg: params.cfg, - context: { - systemPrompt: params.prompt, - messages: [ - { - role: "user", - content: params.userMessage, - timestamp: Date.now(), - }, - ], - }, - options: { - maxTokens, - ...(isCodexSimpleCompletionModel(params.prepared.model) ? {} : { temperature: 0.3 }), - signal: controller.signal, - }, - }); - const errorMessage = extractSimpleCompletionError(result); - if (errorMessage) { - logLabelFailure(params.phase, `completion failed: ${errorMessage}`); - return null; - } - - const text = result.content - .filter(isTextContentBlock) - .map((block) => block.text) - .join("") - .trim(); - return text ? truncateUtf16Safe(text, params.maxLength) || null : null; - } catch (err) { - logLabelFailure(params.phase, `completion failed: ${String(err)}`); - return null; - } finally { - clearTimeout(timeout); + const selection = resolveAttemptSelection(params); + if (!selection) { + throw new Error("conversation label model selection unavailable"); } + const completion = await runIsolatedCompletion({ + config: params.cfg, + provider: selection.runtimeProvider ?? selection.provider, + model: selection.modelId, + authProfileId: selection.profileId ?? params.attempt.preferredProfile, + agentId: params.agentId, + agentDir: params.agentDir ?? selection.agentDir, + ...(params.agentHarnessRuntimeOverride + ? { agentHarnessRuntimeOverride: params.agentHarnessRuntimeOverride } + : {}), + systemPrompt: params.prompt, + prompt: params.userMessage, + timeoutMs: params.timeoutMs, + streamParams: { maxTokens: CONVERSATION_LABEL_MAX_TOKENS }, + }); + return truncateUtf16Safe(completion.text.trim(), params.maxLength) || null; } -/** Generates a bounded human-readable label for a session, or null on failure. */ +async function runLabelAttempts(params: { + cfg: OpenClawConfig; + agentId: string; + agentDir?: string; + agentHarnessRuntimeOverride?: string; + attempts: readonly ConversationLabelAttempt[]; + userMessage: string; + prompt: string; + timeoutMs: number; + maxLength: number; + normalizeLabel?: (label: string) => string | null; +}): Promise { + const seen = new Set(); + const failures: LabelModelPhase[] = []; + for (const [index, attempt] of params.attempts.entries()) { + const key = resolveAttemptKey({ ...params, attempt }); + if (seen.has(key)) { + continue; + } + seen.add(key); + try { + const label = await completeLabel({ ...params, attempt }); + const normalized = label && params.normalizeLabel ? params.normalizeLabel(label) : label; + if (normalized) { + return normalized; + } + } catch { + failures.push(index === params.attempts.length - 1 ? "primary fallback" : "utility"); + } + } + if (failures.length > 0) { + // Keep provider errors and credentials out of logs while still recording the + // owned operation that failed after every configured route was exhausted. + throw new Error(`conversation label generation failed (${failures.join(", ")})`); + } + return null; +} + +/** Generates a bounded human-readable label for a session, or null for empty output. */ export async function generateConversationLabel( params: ConversationLabelParams, ): Promise { - const { userMessage, prompt, cfg, agentId, agentDir } = params; - const maxLength = resolveMaxLabelLength(params.maxLength); - const resolvedAgentId = agentId ?? resolveDefaultAgentId(cfg); - const utilityPrepared = await prepareLabelModel({ - cfg, - agentId: resolvedAgentId, - agentDir, - attempt: { useUtilityModel: true }, - phase: "utility", - }); - const utilityCompletionAttempted = Boolean(utilityPrepared && !("error" in utilityPrepared)); - if (utilityPrepared && !("error" in utilityPrepared)) { - const label = await completeLabel({ - prepared: utilityPrepared, - cfg, - userMessage, - prompt, - maxLength, - phase: "utility", - }); - if (label) { - return label; - } - } - - const primaryPrepared = await prepareLabelModel({ - cfg, - agentId: resolvedAgentId, - agentDir, - attempt: { useUtilityModel: false }, - phase: "primary fallback", - }); - if ( - !primaryPrepared || - "error" in primaryPrepared || - (utilityCompletionAttempted && selectedLabelModelsMatch(utilityPrepared, primaryPrepared)) - ) { - return null; - } - return await completeLabel({ - prepared: primaryPrepared, - cfg, - userMessage, - prompt, - maxLength, - phase: "primary fallback", + const agentId = params.agentId ?? resolveDefaultAgentId(params.cfg); + const attempts: ConversationLabelAttempt[] = params.modelRef + ? [{ modelRef: params.modelRef }] + : [{ useUtilityModel: true }, { useUtilityModel: false }]; + return await runLabelAttempts({ + cfg: params.cfg, + agentId, + agentDir: params.agentDir, + ...(params.agentHarnessRuntimeOverride + ? { agentHarnessRuntimeOverride: params.agentHarnessRuntimeOverride } + : {}), + attempts, + userMessage: params.userMessage, + prompt: params.prompt, + timeoutMs: resolveTimeoutMs(params.timeoutMs), + maxLength: resolveMaxLabelLength(params.maxLength), }); } @@ -286,12 +196,11 @@ export async function generateConversationLabelWithFallback( const regularAttempt: ConversationLabelAttempt = { modelRef: params.regularModelRef, ...(params.preferredProfile ? { preferredProfile: params.preferredProfile } : {}), - bindAuthOwner: true, }; const utilityRef = params.utilityModelRef?.trim(); let utilityAttempt: ConversationLabelAttempt | undefined; if (utilityRef) { - const candidate: ConversationLabelAttempt = { modelRef: utilityRef, bindAuthOwner: true }; + const candidate: ConversationLabelAttempt = { modelRef: utilityRef }; const utilitySelection = resolveAttemptSelection({ cfg: params.cfg, agentId, @@ -315,56 +224,21 @@ export async function generateConversationLabelWithFallback( utilityAuthProvider && utilityAuthProvider === regularAuthProvider; utilityAttempt = inheritsRegularProfile - ? { modelRef: `${utilityRef}@${params.preferredProfile}`, bindAuthOwner: true } + ? { modelRef: `${utilityRef}@${params.preferredProfile}` } : candidate; } - const attempts: ConversationLabelAttempt[] = [ - ...(utilityAttempt ? [utilityAttempt] : []), - regularAttempt, - ]; - const seen = new Set(); - const maxLength = resolveMaxLabelLength(params.maxLength); - let previousCompletedModel: PreparedLabelModel | null = null; - for (const attempt of attempts) { - const key = resolveAttemptKey({ - cfg: params.cfg, - agentId, - agentDir: params.agentDir, - attempt, - }); - if (seen.has(key)) { - continue; - } - seen.add(key); - const phase = attempt === regularAttempt ? "primary fallback" : "utility"; - const prepared = await prepareLabelModel({ - cfg: params.cfg, - agentId, - agentDir: params.agentDir, - attempt, - phase, - }); - if (!prepared || "error" in prepared) { - continue; - } - if (previousCompletedModel && selectedLabelModelsMatch(previousCompletedModel, prepared)) { - continue; - } - previousCompletedModel = prepared; - const label = await completeLabel({ - prepared, - cfg: params.cfg, - userMessage: params.userMessage, - prompt: params.prompt, - maxLength, - phase, - }); - if (label) { - const normalized = params.normalizeLabel ? params.normalizeLabel(label) : label; - if (normalized) { - return normalized; - } - } - } - return null; + return await runLabelAttempts({ + cfg: params.cfg, + agentId, + agentDir: params.agentDir, + ...(params.agentHarnessRuntimeOverride + ? { agentHarnessRuntimeOverride: params.agentHarnessRuntimeOverride } + : {}), + attempts: [...(utilityAttempt ? [utilityAttempt] : []), regularAttempt], + userMessage: params.userMessage, + prompt: params.prompt, + timeoutMs: resolveTimeoutMs(params.timeoutMs), + maxLength: resolveMaxLabelLength(params.maxLength), + normalizeLabel: params.normalizeLabel, + }); } diff --git a/src/gateway/dashboard-session-title.test.ts b/src/gateway/dashboard-session-title.test.ts index 025be9af0def..270e2accfd4a 100644 --- a/src/gateway/dashboard-session-title.test.ts +++ b/src/gateway/dashboard-session-title.test.ts @@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; const generateConversationLabelWithFallback = vi.hoisted(() => vi.fn()); const resolveUtilityModelRefForAgent = vi.hoisted(() => vi.fn()); +const readSessionTitleFieldsFromTranscript = vi.hoisted(() => vi.fn()); const updateSessionEntry = vi.hoisted(() => vi.fn()); vi.mock("../agents/utility-model.js", () => ({ resolveUtilityModelRefForAgent })); @@ -10,6 +11,7 @@ vi.mock("../auto-reply/reply/conversation-label-generator.js", () => ({ generateConversationLabelWithFallback, })); vi.mock("../config/sessions/session-accessor.js", () => ({ updateSessionEntry })); +vi.mock("./session-transcript-title-reader.js", () => ({ readSessionTitleFieldsFromTranscript })); import type { SessionEntry } from "../config/sessions/types.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; @@ -51,6 +53,11 @@ describe("maybeGenerateDashboardSessionTitle", () => { generateConversationLabelWithFallback.mockReset(); resolveUtilityModelRefForAgent.mockReset(); updateSessionEntry.mockReset(); + readSessionTitleFieldsFromTranscript.mockReset(); + readSessionTitleFieldsFromTranscript.mockReturnValue({ + firstUserMessage: null, + lastMessagePreview: null, + }); generateConversationLabelWithFallback.mockResolvedValue("Release Planning"); resolveUtilityModelRefForAgent.mockReturnValue("openai/gpt-5.6-luna"); mockSessionUpdate(baseEntry); @@ -116,6 +123,38 @@ describe("maybeGenerateDashboardSessionTitle", () => { ); }); + it("preserves a locked session harness as the title runtime owner", async () => { + const entry = { + ...baseEntry, + agentHarnessId: "codex", + agentRuntimeOverride: "openclaw", + modelSelectionLocked: true, + }; + mockSessionUpdate(entry); + + await expect(maybeGenerateDashboardSessionTitle(titleParams(entry))).resolves.toBe(true); + + expect(generateConversationLabelWithFallback).toHaveBeenCalledWith( + expect.objectContaining({ agentHarnessRuntimeOverride: "codex" }), + ); + }); + + it("preserves a compatible session runtime override for title generation", async () => { + const entry = { + ...baseEntry, + providerOverride: "anthropic", + modelOverride: "claude-fable-5", + agentRuntimeOverride: "claude-cli", + }; + mockSessionUpdate(entry); + + await expect(maybeGenerateDashboardSessionTitle(titleParams(entry))).resolves.toBe(true); + + expect(generateConversationLabelWithFallback).toHaveBeenCalledWith( + expect.objectContaining({ agentHarnessRuntimeOverride: "claude-cli" }), + ); + }); + it("preserves the configured primary auth profile for explicit utility models", async () => { const profiledCfg = { agents: { @@ -201,7 +240,6 @@ describe("maybeGenerateDashboardSessionTitle", () => { ["group subject", { entry: { ...baseEntry, subject: "Release team" } }], ["channel name", { entry: { ...baseEntry, groupChannel: "releases" } }], ["space name", { entry: { ...baseEntry, space: "Engineering" } }], - ["existing session history", { entry: { ...baseEntry, systemSent: true } }], ])("skips %s", async (_name, override) => { await expect( maybeGenerateDashboardSessionTitle({ ...titleParams(), ...override }), @@ -211,6 +249,58 @@ describe("maybeGenerateDashboardSessionTitle", () => { expect(updateSessionEntry).not.toHaveBeenCalled(); }); + it("retries a historical session from the transcript's first user message", async () => { + const entry = { ...baseEntry, systemSent: true }; + readSessionTitleFieldsFromTranscript.mockReturnValue({ + firstUserMessage: "[Mon 2026-08-10 12:00 UTC] Original release plan", + lastMessagePreview: "Latest follow-up", + }); + mockSessionUpdate(entry); + + await expect( + maybeGenerateDashboardSessionTitle({ + ...titleParams(entry), + currentUserMessage: "Latest follow-up", + userMessage: "Latest follow-up", + }), + ).resolves.toBe(true); + + expect(generateConversationLabelWithFallback.mock.calls[0]?.[0]?.userMessage).toBe( + "Original release plan", + ); + }); + + it("preserves attachment-aware input when the first turn is already in the transcript", async () => { + readSessionTitleFieldsFromTranscript.mockReturnValue({ + firstUserMessage: "[Mon 2026-08-10 12:00 UTC] Review this rollout", + lastMessagePreview: "Review this rollout", + }); + + await expect( + maybeGenerateDashboardSessionTitle({ + ...titleParams(), + currentUserMessage: "Review this rollout", + userMessage: "Review this rollout\nDeployment context", + }), + ).resolves.toBe(true); + + expect(generateConversationLabelWithFallback.mock.calls[0]?.[0]?.userMessage).toBe( + "Review this rollout\nDeployment context", + ); + }); + + it("evicts a failed request so later activity can retry", async () => { + generateConversationLabelWithFallback + .mockRejectedValueOnce(new Error("route unavailable")) + .mockResolvedValueOnce("Release Planning"); + + await expect(maybeGenerateDashboardSessionTitle(titleParams())).rejects.toThrow( + "route unavailable", + ); + await expect(maybeGenerateDashboardSessionTitle(titleParams())).resolves.toBe(true); + expect(generateConversationLabelWithFallback).toHaveBeenCalledTimes(2); + }); + it("does not overwrite a name added while the model request is running", async () => { mockSessionUpdate({ ...baseEntry, label: "Manual title" }); diff --git a/src/gateway/dashboard-session-title.ts b/src/gateway/dashboard-session-title.ts index d2e187c5df30..4311d2fe0a48 100644 --- a/src/gateway/dashboard-session-title.ts +++ b/src/gateway/dashboard-session-title.ts @@ -3,8 +3,10 @@ import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice"; import { resolveAgentEffectiveModelPrimary } from "../agents/agent-scope.js"; import { splitTrailingAuthProfile } from "../agents/model-ref-profile.js"; import { resolveSessionModelRef } from "../agents/session-model-ref.js"; +import { resolveSessionRuntimeOverrideForProvider } from "../agents/session-runtime-compat.js"; import { resolveUtilityModelRefForAgent } from "../agents/utility-model.js"; import { generateConversationLabelWithFallback } from "../auto-reply/reply/conversation-label-generator.js"; +import { stripInboundMetadata } from "../auto-reply/reply/strip-inbound-meta.js"; import { updateSessionEntry } from "../config/sessions/session-accessor.js"; import type { SessionEntry } from "../config/sessions/types.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; @@ -12,10 +14,18 @@ import { parseAgentSessionKey } from "../sessions/session-key-utils.js"; import { getOrCreatePromise } from "../shared/lazy-promise.js"; import { stripInlineDirectiveTagsForDisplay } from "../utils/directive-tags.js"; import { isValidAttachmentBase64, type ChatAttachment } from "./chat-attachments.js"; +import { readSessionTitleFieldsFromTranscript } from "./session-transcript-title-reader.js"; type DashboardSessionTitleModelEntry = Pick< SessionEntry, - "authProfileOverride" | "model" | "modelOverride" | "modelProvider" | "providerOverride" + | "agentHarnessId" + | "agentRuntimeOverride" + | "authProfileOverride" + | "model" + | "modelOverride" + | "modelProvider" + | "modelSelectionLocked" + | "providerOverride" >; const DASHBOARD_SESSION_TITLE_MAX_CHARS = 60; @@ -23,11 +33,11 @@ const DASHBOARD_SESSION_TITLE_SOURCE_MAX_CHARS = 1_000; const DASHBOARD_SESSION_TITLE_PROMPT = "Generate a concise session title (3-6 words, max 60 characters) from the user's first message. Use the same language as the message. No emoji. Return only the title."; -// One title request per first turn. Concurrent sends cannot race duplicate model +// One title request per session generation. Concurrent triggers cannot race duplicate model // calls or metadata writes; late callers receive the in-flight promise so they // may await the persisted title before proceeding. Stored promises always -// settle: the label generator aborts internally (TIMEOUT_MS), so a hung model -// call cannot pin an entry here and block future attempts. +// settle: isolated completion enforces a timeout, so a hung model call cannot +// pin an entry here and block future attempts. const sessionTitleRequests = new Map>(); function decodeTextAttachmentPrefix(attachment: ChatAttachment, maxChars: number): string | null { @@ -161,6 +171,11 @@ export async function generateDashboardSessionTitle(params: { return null; } const regularModel = resolveSessionModelRef(params.cfg, params.entry, params.agentId); + const agentHarnessRuntimeOverride = resolveSessionRuntimeOverrideForProvider({ + provider: regularModel.provider, + entry: params.entry, + cfg: params.cfg, + }); const preferredProfile = resolveDashboardTitleAuthProfile({ cfg: params.cfg, agentId: params.agentId, @@ -181,6 +196,7 @@ export async function generateDashboardSessionTitle(params: { prompt: DASHBOARD_SESSION_TITLE_PROMPT, cfg: params.cfg, agentId: params.agentId, + ...(agentHarnessRuntimeOverride ? { agentHarnessRuntimeOverride } : {}), ...(utilityModelRef ? { utilityModelRef } : {}), regularModelRef, ...(preferredProfile ? { preferredProfile } : {}), @@ -197,6 +213,7 @@ export async function maybeGenerateDashboardSessionTitle(params: { sessionId: string; sessionKey: string; storePath: string; + currentUserMessage?: string; userMessage: string; }): Promise { const sourceText = params.userMessage.trim(); @@ -221,14 +238,10 @@ export async function maybeGenerateSessionTitle(params: { sessionId: string; sessionKey: string; storePath: string; + currentUserMessage?: string; userMessage: string; }): Promise { - const sourceText = params.userMessage.trim(); - if ( - hasExplicitSessionName(params.entry) || - params.entry?.systemSent === true || - params.entry?.sessionId !== params.sessionId - ) { + if (hasExplicitSessionName(params.entry) || params.entry?.sessionId !== params.sessionId) { return { kind: "skipped" }; } @@ -237,6 +250,32 @@ export async function maybeGenerateSessionTitle(params: { if (existing) { return { kind: "in-flight", settled: existing }; } + + // A retry may be triggered by a later send or by discussion open. Always + // title the session from its original user message when the transcript owns it. + const transcriptSource = readSessionTitleFieldsFromTranscript({ + agentId: params.agentId, + sessionEntry: params.entry, + sessionId: params.sessionId, + sessionKey: params.sessionKey, + storePath: params.storePath, + }).firstUserMessage; + const transcriptText = transcriptSource + ? stripInlineDirectiveTagsForDisplay(stripInboundMetadata(transcriptSource)).text.trim() + : ""; + const currentText = params.currentUserMessage + ? stripInlineDirectiveTagsForDisplay(params.currentUserMessage).text.trim() + : ""; + // A first-turn transcript may win the persistence race before title work starts. + // When it is the current turn, retain the supplied attachment-enriched source. + const sourceText = + !transcriptText || (currentText && currentText === transcriptText) + ? params.userMessage.trim() + : transcriptText; + if (!sourceText) { + return { kind: "skipped" }; + } + const request = getOrCreatePromise( sessionTitleRequests, requestKey, diff --git a/src/gateway/server-methods/chat-send-background.ts b/src/gateway/server-methods/chat-send-background.ts index 13071fcecfed..305c4ba20c31 100644 --- a/src/gateway/server-methods/chat-send-background.ts +++ b/src/gateway/server-methods/chat-send-background.ts @@ -71,6 +71,7 @@ export function scheduleChatDashboardSessionTitle(params: { sessionId: titleSessionId, sessionKey: params.sessionKey, storePath: params.storePath, + currentUserMessage: params.request.rawMessage, userMessage: titleSource, }); if (updated) { diff --git a/src/gateway/server-methods/session-discussion.test.ts b/src/gateway/server-methods/session-discussion.test.ts index 693d32724486..cd670dc1eea5 100644 --- a/src/gateway/server-methods/session-discussion.test.ts +++ b/src/gateway/server-methods/session-discussion.test.ts @@ -174,7 +174,7 @@ describe("session discussion gateway methods", () => { sessionId: "session-1", sessionKey, storePath, - userMessage: "Plan the release", + userMessage: "", }), ); expect(persistedEntry?.displayName).toBe("Release Planning"); @@ -187,6 +187,26 @@ describe("session discussion gateway methods", () => { ); }); + it("attempts a title when system prompt state already exists", async () => { + const entry: SessionEntry = { sessionId: "session-1", updatedAt: 1, systemSent: true }; + mockSession(entry); + mocks.readSessionTitleFields.mockReturnValue({ + firstUserMessage: "Plan the release", + lastMessagePreview: null, + }); + mocks.updateSessionEntry.mockImplementation(async (_scope, update) => { + const patch = await update({ ...entry }); + return patch ? { ...entry, ...patch } : entry; + }); + const registered = provider(); + mocks.getProvider.mockReturnValue(registered.value); + + await invoke("session.discussion.open", { sessionKey }); + + expect(mocks.maybeGenerateSessionTitle).toHaveBeenCalledOnce(); + expect(mocks.generateConversationLabelWithFallback).toHaveBeenCalledOnce(); + }); + it("titles via the canonical session key when opened through an alias key", async () => { const entry: SessionEntry = { sessionId: "session-1", updatedAt: 1 }; mocks.loadSessionTarget.mockReturnValue({ diff --git a/src/gateway/server-methods/session-discussion.ts b/src/gateway/server-methods/session-discussion.ts index 8460db7de82a..15936ddc6237 100644 --- a/src/gateway/server-methods/session-discussion.ts +++ b/src/gateway/server-methods/session-discussion.ts @@ -7,10 +7,9 @@ import { validateSessionDiscussionOpenParams, validateSessionDiscussionOpenResult, } from "../../../packages/gateway-protocol/src/index.js"; -import { stripInboundMetadata } from "../../auto-reply/reply/strip-inbound-meta.js"; import { getSessionDiscussionProvider } from "../../plugins/session-discussion-registry.js"; import { hasExplicitSessionName, maybeGenerateSessionTitle } from "../dashboard-session-title.js"; -import { readSessionTitleFieldsFromTranscript } from "../session-transcript-title-reader.js"; +import { formatForLog } from "../ws-log.js"; import { emitSessionsChanged } from "./session-change-event.js"; import { loadAccessorSessionEntryForGatewayTarget } from "./sessions-shared.js"; import type { GatewayRequestContext, GatewayRequestHandlers } from "./types.js"; @@ -30,20 +29,7 @@ async function maybeGenerateTitleBeforeDiscussionOpen(params: { }); const { entry } = resolved; const sessionId = entry?.sessionId; - if (!entry || !sessionId || entry.systemSent === true || hasExplicitSessionName(entry)) { - return; - } - const fields = readSessionTitleFieldsFromTranscript({ - agentId: resolved.target.agentId, - sessionEntry: entry, - sessionId, - sessionKey: resolved.canonicalKey, - storePath: resolved.storePath, - }); - const userMessage = fields.firstUserMessage - ? stripInboundMetadata(fields.firstUserMessage).trim() - : ""; - if (!userMessage) { + if (!entry || !sessionId || hasExplicitSessionName(entry)) { return; } @@ -59,7 +45,7 @@ async function maybeGenerateTitleBeforeDiscussionOpen(params: { // the open request addresses the session through an alias key. sessionKey: resolved.canonicalKey, storePath: resolved.storePath, - userMessage, + userMessage: "", }).then(async (attempt) => { if (attempt.kind === "in-flight") { await attempt.settled.catch(() => {}); @@ -67,6 +53,12 @@ async function maybeGenerateTitleBeforeDiscussionOpen(params: { } return attempt.kind === "persisted"; }); + const observedTitleRequest = titleRequest.catch((error: unknown) => { + params.context.logGateway.warn( + `dashboard session title generation failed: ${formatForLog(error)}`, + ); + return false; + }); let timeout: NodeJS.Timeout | undefined; let persisted = false; // Discussion open waits at most 10 seconds for best-effort titling. @@ -74,7 +66,7 @@ async function maybeGenerateTitleBeforeDiscussionOpen(params: { // picks up any title that completes after the timeout. try { persisted = await Promise.race([ - titleRequest.catch(() => false), + observedTitleRequest, new Promise((resolve) => { timeout = setTimeout(() => resolve(false), DISCUSSION_TITLE_TIMEOUT_MS); timeout.unref?.(); @@ -94,8 +86,11 @@ async function maybeGenerateTitleBeforeDiscussionOpen(params: { reason: "chat.title", }); } - } catch { + } catch (error) { // Titling is best-effort; provider open remains the authoritative operation. + params.context.logGateway.warn( + `dashboard session title generation failed: ${formatForLog(error)}`, + ); } } diff --git a/src/plugin-sdk/agent-harness-runtime.test.ts b/src/plugin-sdk/agent-harness-runtime.test.ts index aa44e224aa9e..a6840e2aa05f 100644 --- a/src/plugin-sdk/agent-harness-runtime.test.ts +++ b/src/plugin-sdk/agent-harness-runtime.test.ts @@ -210,6 +210,15 @@ describe("agent harness runtime SDK facade", () => { NonNullable["runtimePolicy"] >().toEqualTypeOf(); }); + + it("exports the V2 isolated-completion authorization contract through the harness", () => { + type IsolatedCompletionV2 = NonNullable; + + expectTypeOf[0]["authorization"]["owner"]>().toEqualTypeOf< + "host" | "harness" + >(); + expectTypeOf>["assistant"]>().not.toBeNever(); + }); }); describe("agent harness user input helpers", () => { From fc45a0f1e682e02758b427392bddc825219ae8ac Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:15:15 -0700 Subject: [PATCH 005/165] fix(update): show tracked status for detached deployments (#122415) * fix(update): track main from detached deployments * test(update): use canonical temp directory helper * test(update): keep detached tracking regression compact --- src/infra/update-channels.ts | 8 ++++++ src/infra/update-check.test.ts | 7 ++++- src/infra/update-check.ts | 20 +++++++++----- src/infra/update-runner-git-preflight.ts | 10 ++++--- src/infra/update-startup.test.ts | 33 +++++++++++++++++++++++- src/infra/update-startup.ts | 10 ++++--- 6 files changed, 71 insertions(+), 17 deletions(-) diff --git a/src/infra/update-channels.ts b/src/infra/update-channels.ts index a40205a30624..83c4c344e33b 100644 --- a/src/infra/update-channels.ts +++ b/src/infra/update-channels.ts @@ -25,6 +25,14 @@ export const UPDATE_EFFECTIVE_CHANNEL_ENV = "OPENCLAW_UPDATE_EFFECTIVE_CHANNEL"; /** Git branch that represents the development update stream. */ export const DEV_BRANCH = "main"; +/** Resolves current tracking, or the configured Dev branch for detached HEAD. */ +export function resolveDevUpstreamRef(branch?: string | null, detached = false): string | null { + if (branch !== "HEAD") { + return "@{upstream}"; + } + return detached ? `${DEV_BRANCH}@{upstream}` : null; +} + /** Normalizes config or CLI channel input to a supported update channel. */ export function normalizeUpdateChannel(value?: string | null): UpdateChannel | null { const normalized = normalizeOptionalLowercaseString(value); diff --git a/src/infra/update-check.test.ts b/src/infra/update-check.test.ts index 411664e94fd7..9d7e75df0d57 100644 --- a/src/infra/update-check.test.ts +++ b/src/infra/update-check.test.ts @@ -627,7 +627,7 @@ describe("formatGitInstallLabel", () => { }); describe("checkUpdateStatus", () => { - it("uses a matching receipt upstream only for the detached installed revision", async () => { + it("resolves detached dev tracking before matching update receipts", async () => { await withTestDir({ prefix: "openclaw-update-check-receipt-fallback-" }, async (base) => { const sourceRoot = path.join(base, "source"); const localRoot = path.join(base, "local"); @@ -650,9 +650,14 @@ describe("checkUpdateStatus", () => { includeRegistry: false, fetchGit: params.fetch ?? false, timeoutMs: 5000, + useDetachedDevUpstream: true, ...(params.fallback ? { gitUpstreamFallback: params.fallback } : {}), }); + expect((await readStatus()).git?.upstream).toBe("origin/main"); + await runGit(localRoot, "branch", "--unset-upstream", "main"); + expect((await readStatus()).git?.upstream).toBeNull(); + const current = await readStatus({ fetch: true, fallback }); expect(current.git).toMatchObject({ branch: "HEAD", diff --git a/src/infra/update-check.ts b/src/infra/update-check.ts index f9ebf69af8f1..4cc978ee55b1 100644 --- a/src/infra/update-check.ts +++ b/src/infra/update-check.ts @@ -10,7 +10,7 @@ import { } from "./detect-package-manager.js"; import { compareOpenClawReleaseVersions } from "./npm-registry-spec.js"; import { compareValidSemver, normalizeLegacyDotBetaVersion } from "./semver.js"; -import { channelToNpmTag, type UpdateChannel } from "./update-channels.js"; +import { channelToNpmTag, resolveDevUpstreamRef, type UpdateChannel } from "./update-channels.js"; import { fetchNpmPackageTargetStatus, type NpmMetadataCommandRunner, @@ -229,6 +229,7 @@ async function checkGitUpdateStatus(params: { root: string; timeoutMs?: number; fetch?: boolean; + useDetachedDevUpstream?: boolean; upstreamFallback?: { currentSha: string; upstreamRef: string }; }): Promise { const timeoutMs = params.timeoutMs ?? 6000; @@ -248,7 +249,7 @@ async function checkGitUpdateStatus(params: { fetchOk: null, }; - const [branchRes, shaRes, commitAtRes, tagRes, upstreamRes, dirtyRes] = await Promise.all([ + const [branchRes, shaRes, commitAtRes, tagRes, dirtyRes] = await Promise.all([ runCommandWithTimeout(["git", "-C", root, "rev-parse", "--abbrev-ref", "HEAD"], { timeoutMs, }).catch(() => null), @@ -261,9 +262,6 @@ async function checkGitUpdateStatus(params: { runCommandWithTimeout(["git", "-C", root, "describe", "--tags", "--exact-match"], { timeoutMs, }).catch(() => null), - runCommandWithTimeout(["git", "-C", root, "rev-parse", "--abbrev-ref", "@{upstream}"], { - timeoutMs, - }).catch(() => null), runCommandWithTimeout( ["git", "-C", root, "status", "--porcelain", "--", ":!dist/control-ui/"], { @@ -275,6 +273,13 @@ async function checkGitUpdateStatus(params: { return { ...base, error: branchRes?.stderr?.trim() || "git unavailable" }; } const branch = branchRes.stdout.trim() || null; + const trackingRevision = resolveDevUpstreamRef(branch, params.useDetachedDevUpstream); + const upstreamRes = trackingRevision + ? await runCommandWithTimeout( + ["git", "-C", root, "rev-parse", "--abbrev-ref", "--symbolic-full-name", trackingRevision], + { timeoutMs }, + ).catch(() => null) + : null; const sha = shaRes && shaRes.code === 0 ? shaRes.stdout.trim() : null; const commitAtSeconds = @@ -311,8 +316,7 @@ async function checkGitUpdateStatus(params: { // Freeze the post-fetch upstream for both graph queries. Active tracking wins; // a matching successful update receipt keeps intentional detached installs comparable. - const upstreamRevision = - upstreamSource === "tracking" ? "@{upstream}^{commit}" : `${upstream}^{commit}`; + const upstreamRevision = `${upstreamSource === "tracking" ? trackingRevision : upstream}^{commit}`; const upstreamCommitRes = canCompareUpstream && upstream && sha ? await runCommandWithTimeout( @@ -608,6 +612,7 @@ export async function checkUpdateStatus(params: { root: string | null; timeoutMs?: number; fetchGit?: boolean; + useDetachedDevUpstream?: boolean; gitUpstreamFallback?: { currentSha: string; upstreamRef: string }; includeRegistry?: boolean; registryChannel?: UpdateChannel; @@ -658,6 +663,7 @@ export async function checkUpdateStatus(params: { root, timeoutMs, fetch: Boolean(params.fetchGit), + useDetachedDevUpstream: params.useDetachedDevUpstream, upstreamFallback: params.gitUpstreamFallback, }) : Promise.resolve(undefined), diff --git a/src/infra/update-runner-git-preflight.ts b/src/infra/update-runner-git-preflight.ts index 5c6bd0d2421a..02723a3cd9b1 100644 --- a/src/infra/update-runner-git-preflight.ts +++ b/src/infra/update-runner-git-preflight.ts @@ -3,7 +3,7 @@ import os from "node:os"; import path from "node:path"; import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization"; import { trimLogTail } from "./restart-sentinel.js"; -import { DEV_BRANCH } from "./update-channels.js"; +import { DEV_BRANCH, resolveDevUpstreamRef } from "./update-channels.js"; import { resolveDevUpdateTargetRevision, type DevUpdateTarget } from "./update-dev-target.js"; import { managerInstallArgs, @@ -210,9 +210,11 @@ async function resolveUpstreamCandidates(params: { ); } } - const upstreamRefs = params.needsCheckoutMain - ? [`${DEV_BRANCH}@{upstream}`, ...remoteBranchRefs] - : ["@{upstream}"]; + const trackingRevision = resolveDevUpstreamRef( + params.needsCheckoutMain ? "HEAD" : DEV_BRANCH, + true, + ); + const upstreamRefs = [...(trackingRevision ? [trackingRevision] : []), ...remoteBranchRefs]; let upstreamSha: string | null = null; let selectedDevUpstream: string | null = null; let sawResolvableUpstreamRef = false; diff --git a/src/infra/update-startup.test.ts b/src/infra/update-startup.test.ts index 28faa198cfc7..00e54c5e473f 100644 --- a/src/infra/update-startup.test.ts +++ b/src/infra/update-startup.test.ts @@ -1097,6 +1097,7 @@ describe("update-startup", () => { timeoutMs: 2500, fetchGit: true, includeRegistry: false, + useDetachedDevUpstream: true, }); expect(resolveNpmChannelTag).not.toHaveBeenCalled(); expect(getUpdateAvailable()).toEqual({ @@ -1214,6 +1215,32 @@ describe("update-startup", () => { }); }); + it("continues managed dev campaigns from a detached tracked deployment", async () => { + mockDevGitStatus({ branch: "HEAD", upstreamSource: "tracking" }); + const runAutoUpdate = createAutoUpdateSuccessMock(); + + await runGatewayUpdateCheck({ + cfg: { update: { channel: "dev", auto: { enabled: true } } }, + log: { info: vi.fn() }, + isNixMode: false, + allowInTests: true, + activeWorkInspectors: idleActiveWorkInspectors(), + runAutoUpdate, + }); + + expect(getUpdateSchedule()?.campaign?.state).toBe("countdown"); + await vi.advanceTimersByTimeAsync(60_000); + expect(runAutoUpdate).toHaveBeenCalledWith( + expect.objectContaining({ + devTarget: { + mode: "tracked", + upstreamRef: "origin/main", + upstreamSha: "upstream-sha", + }, + }), + ); + }); + it.each([ { name: "successful install", status: "ok", reason: undefined }, { @@ -1256,6 +1283,7 @@ describe("update-startup", () => { timeoutMs: 2500, fetchGit: true, includeRegistry: false, + useDetachedDevUpstream: true, gitUpstreamFallback: { currentSha: "current-sha", upstreamRef: "origin/main" }, }); expect(getUpdateSchedule()?.campaign?.state).toBe("countdown"); @@ -1275,7 +1303,10 @@ describe("update-startup", () => { { name: "ahead", git: { ahead: 1, behind: 0 } }, { name: "diverged", git: { ahead: 1, behind: 2 } }, { name: "non-main", git: { branch: "feature" } }, - { name: "detached", git: { branch: "HEAD" } }, + { + name: "detached without tracking", + git: { branch: "HEAD", upstream: null, upstreamSha: null, ahead: null, behind: null }, + }, ])("does not announce an automatic dev campaign for a $name checkout", async ({ git }) => { mockDevGitStatus(git); const runAutoUpdate = createAutoUpdateSuccessMock(); diff --git a/src/infra/update-startup.ts b/src/infra/update-startup.ts index 6cf38fe5f0df..c49b0724c250 100644 --- a/src/infra/update-startup.ts +++ b/src/infra/update-startup.ts @@ -567,7 +567,7 @@ function clearAutoState(nextState: UpdateCheckState): void { delete nextState.autoFirstSeenAt; } -async function resolveStartupInstallStatus(fetchGit: boolean) { +async function resolveStartupInstallStatus(checkDevGit: boolean) { const [root, installReceipt] = await Promise.all([ resolveOpenClawPackageRoot({ moduleUrl: import.meta.url, @@ -583,8 +583,9 @@ async function resolveStartupInstallStatus(fetchGit: boolean) { const status = await checkUpdateStatus({ root, timeoutMs: 2500, - fetchGit, + fetchGit: checkDevGit, includeRegistry: false, + ...(checkDevGit ? { useDetachedDevUpstream: true } : {}), ...(gitUpstreamFallback ? { gitUpstreamFallback } : {}), }); return { root, status, installReceipt }; @@ -1121,10 +1122,11 @@ export async function runGatewayUpdateCheck(params: { reason: EXTERNAL_SUPERVISOR_UPDATE_REQUIRED_REASON, }); } - const hasTrackedMain = git.branch === DEV_BRANCH && git.upstreamSource === "tracking"; + const hasTrackedDevUpstream = + (git.branch === DEV_BRANCH || git.branch === "HEAD") && git.upstreamSource === "tracking"; const hasReceiptBackedDetachedHead = git.branch === "HEAD" && git.upstreamSource === "receipt"; const canRunTrackedDevCampaign = - (hasTrackedMain || hasReceiptBackedDetachedHead) && git.ahead === 0; + (hasTrackedDevUpstream || hasReceiptBackedDetachedHead) && git.ahead === 0; if (shouldRunAutoUpdate && canRunTrackedDevCampaign) { const lastAttemptAt = state.autoLastAttemptAt ? Date.parse(state.autoLastAttemptAt) : null; const recentAttempt = From 6b0be0215fb8f54bf55b0a36b85678b16d7b096b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:15:32 -0700 Subject: [PATCH 006/165] refactor(ui): split new-session page into draft owners (#122413) * refactor(ui): split new-session page into draft owners * refactor(ui): delete duplicated draft plumbing * chore(lint): ratchet max-lines baseline after new-session split --- config/max-lines-baseline.txt | 1 - ui/src/pages/new-session/cloud-target.ts | 2 +- .../pages/new-session/draft-gateway-state.ts | 537 ++++ .../new-session/draft-place-browser.test.ts | 111 + .../pages/new-session/draft-place-browser.ts | 596 ++++ ui/src/pages/new-session/draft-place-state.ts | 744 +++++ .../new-session/draft-submission-flow.test.ts | 205 ++ .../new-session/draft-submission-flow.ts | 690 +++++ .../new-session/new-session-page.test.ts | 265 +- ui/src/pages/new-session/new-session-page.ts | 2582 ++--------------- ui/src/pages/new-session/place-picker.test.ts | 3 +- ui/src/pages/new-session/place-picker.ts | 39 +- 12 files changed, 3245 insertions(+), 2530 deletions(-) create mode 100644 ui/src/pages/new-session/draft-gateway-state.ts create mode 100644 ui/src/pages/new-session/draft-place-browser.test.ts create mode 100644 ui/src/pages/new-session/draft-place-browser.ts create mode 100644 ui/src/pages/new-session/draft-place-state.ts create mode 100644 ui/src/pages/new-session/draft-submission-flow.test.ts create mode 100644 ui/src/pages/new-session/draft-submission-flow.ts diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt index e4bf2bb2b02c..6e128a973367 100644 --- a/config/max-lines-baseline.txt +++ b/config/max-lines-baseline.txt @@ -921,7 +921,6 @@ ui/src/pages/chat/tool-stream.ts ui/src/pages/config/config-page.ts ui/src/pages/config/view.browser.test.ts ui/src/pages/cron/view.ts -ui/src/pages/new-session/new-session-page.ts ui/src/pages/plugins/plugins-page.ts ui/src/pages/plugins/view.ts ui/src/pages/sessions/sessions-page.ts diff --git a/ui/src/pages/new-session/cloud-target.ts b/ui/src/pages/new-session/cloud-target.ts index a4acfb852903..f00f32261541 100644 --- a/ui/src/pages/new-session/cloud-target.ts +++ b/ui/src/pages/new-session/cloud-target.ts @@ -50,7 +50,7 @@ export function renderSessionMenuItem(params: SessionMenuItemOptions, submitting } export function renderCloudProfileMenuItems(params: { - profiles: DraftCloudProfile[]; + profiles: readonly DraftCloudProfile[]; selectedId: string; submitting: boolean; icon?: unknown; diff --git a/ui/src/pages/new-session/draft-gateway-state.ts b/ui/src/pages/new-session/draft-gateway-state.ts new file mode 100644 index 000000000000..e4fcd67afbfc --- /dev/null +++ b/ui/src/pages/new-session/draft-gateway-state.ts @@ -0,0 +1,537 @@ +import { initialState, Task, TaskStatus } from "@lit/task"; +import type { ReactiveControllerHost } from "lit"; +import type { + UsersPrefsGetResult, + UsersPrefsSetResult, +} from "../../../../packages/gateway-protocol/src/index.js"; +import type { ApplicationContext } from "../../app/context.ts"; +import { t } from "../../i18n/index.ts"; +import { isGatewayMethodAdvertised } from "../../lib/gateway-methods.ts"; +import { normalizeAgentId } from "../../lib/sessions/session-key.ts"; +import * as catalog from "./catalog-target.ts"; +import { + CLOUD_PROFILE_RETRY_DELAYS_MS, + discoverCloudProfiles, + selectProfiles, +} from "./cloud-profile-discovery.ts"; +import { + resolveScope, + resolveSubmissionOutcomeReason, + type SubmissionOutcomeReason, +} from "./cloud-recovery-state.ts"; +import type { DraftCloudProfile } from "./discovery.ts"; +import { discoverGatewayName } from "./gateway-name-discovery.ts"; +import type { NewSessionRouteData } from "./location.ts"; +import { + decodeIdentityPreferences, + encodeIdentityPreferences, + loadBrowserPreferences, + loadNewSessionPreference, + patchNewSessionPreference, + PREFS_MIGRATION_KEY, + replaceBrowserPreference, + type NewSessionPreference, +} from "./preferences.ts"; + +const CATALOG_RETRY_DELAYS_MS = [0, 1_000, 3_000] as const; + +type DraftGatewaySnapshot = Readonly<{ + context: ApplicationContext | undefined; + data: NewSessionRouteData | undefined; + isConnected: boolean; + isAdmin: boolean; + canStartAsDraft: boolean; + visibility: "normal" | "draft" | "incognito"; + cloudProfileId: string; + pendingCloud: Readonly<{ + sessionKey: string; + gatewayUrl: string; + recoveryScope: string; + }>; + agentsHydrated: boolean; +}>; + +type DraftGatewayCallbacks = { + requestUpdate: () => void; + updateComplete: () => Promise; + onInvalidate: (resetHostSelection: boolean, outcome: SubmissionOutcomeReason) => void; + onVisibilityRetired: () => void; + onCloudProfileCleared: () => void; + onCloudState: (error: string | null) => void; + onPendingCloudReset: () => void; + onRecoveryReady: (gatewayUrl: string, recoveryScope: string) => void; + onAdoptAgentDefaults: () => void; +}; + +export class DraftGatewayState { + private gatewayNameValue = ""; + private cloudProfilesValue: DraftCloudProfile[] = []; + private cloudProfilesReadyValue = false; + private catalogRetryingValue = false; + private gatewaySource: ApplicationContext["gateway"] | null = null; + private gatewayClientValue: ApplicationContext["gateway"]["snapshot"]["client"] = null; + private gatewayUrlValue = ""; + private gatewayRecoveryScopeValue = ""; + private gatewayRecoveryScopeReady = false; + private gatewayConnectedValue = false; + private gatewayConnectionEpochValue = 0; + private catalogRetryScope = ""; + private catalogRetryAttempt = 0; + private catalogRetryTimer: ReturnType | undefined; + private cloudProfileRetryAttempt = 0; + private cloudProfileRetryTimer: ReturnType | undefined; + private preferenceScope = ""; + private preferenceModeValue: "local" | "loading" | "remote" = "local"; + private identityPreferences: Record = {}; + private preferenceLoad: Promise = Promise.resolve(); + private preferenceWrite: Promise = Promise.resolve(); + + private readonly gatewayNameTask: Task; + private readonly cloudProfileTask: Task; + + constructor( + host: ReactiveControllerHost, + private readonly read: () => DraftGatewaySnapshot, + private readonly callbacks: DraftGatewayCallbacks, + ) { + this.gatewayNameTask = new Task(host, { + args: () => + [ + this.read().isConnected && this.gatewayConnectedValue ? this.gatewayClientValue : null, + isGatewayMethodAdvertised(this.read().context?.gateway.snapshot ?? {}, "system.info") === + true, + this.gatewayConnectionEpochValue, + ] as const, + task: ([client, advertised, _connectionEpoch], { signal }) => + discoverGatewayName(client, advertised, signal), + onComplete: (name) => { + this.gatewayNameValue = name; + this.callbacks.requestUpdate(); + }, + }); + this.cloudProfileTask = new Task(host, { + args: () => + [ + this.read().isConnected && this.gatewayConnectedValue ? this.gatewayClientValue : null, + this.gatewayConnectionEpochValue, + this.read().isAdmin, + this.gatewayRecoveryScopeValue, + ] as const, + task: ([client, _connectionEpoch, admin]) => + client ? discoverCloudProfiles(client, admin) : initialState, + onComplete: (profiles) => { + this.resetCloudProfileRetry(); + this.applyCloudProfiles(profiles); + this.cloudProfilesReadyValue = true; + this.callbacks.requestUpdate(); + }, + onError: () => { + this.cloudProfilesValue = []; + this.cloudProfilesReadyValue = false; + this.scheduleCloudProfileRetry(); + this.callbacks.requestUpdate(); + }, + }); + } + + get gatewayName(): string { + return this.gatewayNameValue; + } + + get cloudProfiles(): readonly DraftCloudProfile[] { + return this.cloudProfilesValue; + } + + get cloudProfilesReady(): boolean { + return this.cloudProfilesReadyValue; + } + + get cloudProfilesPending(): boolean { + return this.cloudProfileTask.status === TaskStatus.PENDING; + } + + get catalogRetrying(): boolean { + return this.catalogRetryingValue; + } + + get client(): ApplicationContext["gateway"]["snapshot"]["client"] { + return this.gatewayClientValue; + } + + get gatewayUrl(): string { + return this.gatewayUrlValue; + } + + get recoveryScope(): string { + return this.gatewayRecoveryScopeValue; + } + + get connected(): boolean { + return this.gatewayConnectedValue; + } + + get connectionEpoch(): number { + return this.gatewayConnectionEpochValue; + } + + get preferenceLoading(): boolean { + return this.preferenceModeValue === "loading"; + } + + synchronize(gateway: ApplicationContext["gateway"]) { + const snapshot = gateway.snapshot; + const connected = snapshot.phase === "connected"; + const firstBind = this.gatewaySource === null; + const gatewayUrlChanged = !firstBind && this.gatewayUrlValue !== gateway.connection.gatewayUrl; + const identityChanged = + !firstBind && (this.gatewaySource !== gateway || this.gatewayClientValue !== snapshot.client); + const connectionChanged = !firstBind && this.gatewayConnectedValue !== connected; + const becameConnected = connected && (identityChanged || !this.gatewayConnectedValue); + const recoveryScopeBecameReady = + connected && snapshot.client?.recoveryScopeReady === true && !this.gatewayRecoveryScopeReady; + const recoveryScope = resolveScope( + { client: snapshot.client, connected }, + this.gatewayRecoveryScopeValue, + firstBind, + ); + this.gatewaySource = gateway; + this.gatewayClientValue = snapshot.client; + this.gatewayUrlValue = gateway.connection.gatewayUrl; + this.gatewayRecoveryScopeValue = recoveryScope.next; + this.gatewayRecoveryScopeReady = snapshot.client?.recoveryScopeReady === true; + this.gatewayConnectedValue = connected; + if (this.read().visibility === "draft" && !this.read().canStartAsDraft) { + this.callbacks.onVisibilityRetired(); + } + if (gatewayUrlChanged || identityChanged || connectionChanged || recoveryScope.changed) { + const gatewayIdentityChanged = gatewayUrlChanged || recoveryScope.changed; + this.invalidateDiscovery( + gatewayIdentityChanged, + resolveSubmissionOutcomeReason({ + gatewayIdentityChanged, + cloudDraftOwned: Boolean(this.read().pendingCloud.sessionKey), + }), + ); + } + if ( + firstBind || + gatewayUrlChanged || + recoveryScope.changed || + recoveryScopeBecameReady || + becameConnected + ) { + const pending = this.read().pendingCloud; + if ( + pending.gatewayUrl && + (pending.gatewayUrl !== this.gatewayUrlValue || + pending.recoveryScope !== this.gatewayRecoveryScopeValue) + ) { + this.callbacks.onPendingCloudReset(); + } + if (connected && snapshot.client?.recoveryScopeReady) { + this.callbacks.onRecoveryReady(this.gatewayUrlValue, this.gatewayRecoveryScopeValue); + } + } + if (becameConnected) { + this.gatewayConnectionEpochValue += 1; + this.retryPendingCatalogTarget(); + } + this.synchronizeIdentityPreferences(snapshot.selfUser?.id); + this.callbacks.requestUpdate(); + } + + invalidateDiscovery(resetHostSelection: boolean, submissionOutcome: SubmissionOutcomeReason) { + this.gatewayNameValue = ""; + this.cloudProfilesValue = []; + this.cloudProfilesReadyValue = false; + this.resetCloudProfileRetry(); + this.callbacks.onInvalidate(resetHostSelection, submissionOutcome); + this.callbacks.requestUpdate(); + } + + retryPendingCatalogTarget() { + const { data } = this.read(); + if (this.catalogRetryingValue) { + return; + } + if (!this.gatewayConnectedValue || !catalog.isTarget(data) || catalog.isResolvedTarget(data)) { + globalThis.clearTimeout(this.catalogRetryTimer); + this.catalogRetryTimer = undefined; + this.catalogRetryScope = ""; + this.catalogRetryAttempt = 0; + return; + } + const retryScope = `${this.gatewayConnectionEpochValue}:${catalog.routeKey(data)}`; + if (this.catalogRetryScope !== retryScope) { + globalThis.clearTimeout(this.catalogRetryTimer); + this.catalogRetryTimer = undefined; + this.catalogRetryScope = retryScope; + this.catalogRetryAttempt = 0; + } + if (this.catalogRetryTimer || this.catalogRetryAttempt >= CATALOG_RETRY_DELAYS_MS.length) { + return; + } + const delayMs = CATALOG_RETRY_DELAYS_MS[this.catalogRetryAttempt]; + this.catalogRetryAttempt += 1; + this.catalogRetryTimer = globalThis.setTimeout(() => { + this.catalogRetryTimer = undefined; + const current = this.read(); + if ( + this.catalogRetryScope !== retryScope || + !this.gatewayConnectedValue || + !catalog.isTarget(current.data) || + catalog.isResolvedTarget(current.data) + ) { + return; + } + const revalidation = current.context?.revalidate("new-session"); + if (!revalidation) { + return; + } + void revalidation + .catch(() => undefined) + .then(() => this.callbacks.updateComplete()) + .then(() => this.retryPendingCatalogTarget()); + }, delayMs); + } + + readonly handleCatalogRetry = () => { + const { context, data } = this.read(); + if ( + this.catalogRetryingValue || + !this.gatewayConnectedValue || + !catalog.isTarget(data) || + catalog.isResolvedTarget(data) + ) { + return; + } + const revalidation = context?.revalidate("new-session"); + if (!revalidation) { + return; + } + globalThis.clearTimeout(this.catalogRetryTimer); + this.catalogRetryTimer = undefined; + this.catalogRetryingValue = true; + this.callbacks.requestUpdate(); + void revalidation + .catch(() => undefined) + .then(() => this.callbacks.updateComplete()) + .finally(() => { + this.catalogRetryingValue = false; + this.retryPendingCatalogTarget(); + this.callbacks.requestUpdate(); + }); + }; + + readPreference(agentId: string): NewSessionPreference | null { + const snapshot = this.read(); + if (catalog.isTarget(snapshot.data) || snapshot.pendingCloud.sessionKey) { + return null; + } + return this.preferenceModeValue === "remote" + ? (this.identityPreferences[normalizeAgentId(agentId)] ?? null) + : loadNewSessionPreference(this.gatewayUrlValue, agentId); + } + + persistPreference(agentIdValue: string, workspace: string, patch: NewSessionPreference) { + const snapshot = this.read(); + if (catalog.isTarget(snapshot.data) || snapshot.pendingCloud.sessionKey) { + return; + } + const agentId = normalizeAgentId(agentIdValue); + const nextPatch = { workspace, ...patch }; + if (this.preferenceModeValue === "local") { + patchNewSessionPreference(this.gatewayUrlValue, agentId, nextPatch); + return; + } + const scope = this.preferenceScope; + const client = this.gatewayClientValue; + const gatewayUrl = this.gatewayUrlValue; + const write = async () => { + await this.preferenceLoad; + if (!client || this.preferenceScope !== scope) { + return; + } + if (this.preferenceModeValue === "local") { + patchNewSessionPreference(gatewayUrl, agentId, nextPatch); + return; + } + const next = { ...this.identityPreferences[agentId], ...nextPatch }; + try { + const result = await client.request("users.prefs.set", { + entries: encodeIdentityPreferences({ [agentId]: next }), + }); + if (result.status !== "ok" || this.preferenceScope !== scope) { + return; + } + this.identityPreferences = { ...this.identityPreferences, [agentId]: next }; + replaceBrowserPreference(gatewayUrl, agentId, next); + this.callbacks.requestUpdate(); + } catch { + // Gateway state is authoritative for identified users; retain the last mirrored value. + } + }; + this.preferenceWrite = this.preferenceWrite.then(write, write); + } + + disconnect() { + this.gatewaySource = null; + this.gatewayClientValue = null; + this.gatewayConnectedValue = false; + this.gatewayConnectionEpochValue = 0; + this.catalogRetryScope = ""; + this.catalogRetryAttempt = 0; + globalThis.clearTimeout(this.catalogRetryTimer); + this.catalogRetryTimer = undefined; + void this.gatewayNameTask.run([null, false, -1]); + void this.cloudProfileTask.run([null, -1, false, ""]); + this.resetCloudProfileRetry(); + } + + private applyCloudProfiles(profiles: DraftCloudProfile[]) { + const recovery = selectProfiles( + profiles, + this.gatewayClientValue, + this.gatewayRecoveryScopeValue, + ); + this.cloudProfilesValue = recovery.profiles; + const snapshot = this.read(); + const pendingCloud = Boolean(snapshot.pendingCloud.sessionKey); + if ((!this.gatewayConnectedValue || !snapshot.isAdmin) && !pendingCloud) { + this.callbacks.onCloudProfileCleared(); + } + const selectionUnavailable = + !pendingCloud && + Boolean(snapshot.cloudProfileId) && + !profiles.some((profile) => profile.id === snapshot.cloudProfileId); + if (selectionUnavailable) { + this.callbacks.onCloudState(t("newSession.catalogUnavailable")); + } else if (recovery.unsupported) { + this.callbacks.onCloudState(t("newSession.cloudRecoveryUnavailable")); + } else { + this.callbacks.onCloudState(null); + } + } + + private resetCloudProfileRetry() { + globalThis.clearTimeout(this.cloudProfileRetryTimer); + this.cloudProfileRetryTimer = undefined; + this.cloudProfileRetryAttempt = 0; + } + + private scheduleCloudProfileRetry() { + if (this.cloudProfileRetryTimer || !this.gatewayConnectedValue || !this.gatewayClientValue) { + return; + } + if (this.cloudProfileRetryAttempt >= CLOUD_PROFILE_RETRY_DELAYS_MS.length) { + this.applyCloudProfiles([]); + this.cloudProfilesReadyValue = true; + return; + } + const delayMs = CLOUD_PROFILE_RETRY_DELAYS_MS[this.cloudProfileRetryAttempt]; + this.cloudProfileRetryAttempt += 1; + this.cloudProfileRetryTimer = globalThis.setTimeout(() => { + this.cloudProfileRetryTimer = undefined; + if (this.gatewayConnectedValue) { + void this.cloudProfileTask.run(); + } + }, delayMs); + } + + private synchronizeIdentityPreferences(profileId: string | undefined) { + const client = this.gatewayConnectedValue ? this.gatewayClientValue : null; + const context = this.read().context; + const advertised = + context && + isGatewayMethodAdvertised(context.gateway.snapshot, "users.prefs.get") === true && + isGatewayMethodAdvertised(context.gateway.snapshot, "users.prefs.set") === true; + const scope = + client && profileId && advertised + ? `${this.gatewayConnectionEpochValue}\0${profileId}` + : "local"; + if (scope === this.preferenceScope) { + return; + } + this.preferenceScope = scope; + this.identityPreferences = {}; + if (!client || !profileId || !advertised) { + this.preferenceModeValue = "local"; + this.preferenceLoad = Promise.resolve(); + return; + } + this.preferenceModeValue = "loading"; + this.preferenceLoad = this.loadIdentityPreferences({ + client, + gatewayUrl: this.gatewayUrlValue, + scope, + }); + } + + private async loadIdentityPreferences(params: { + client: NonNullable; + gatewayUrl: string; + scope: string; + }): Promise { + try { + const result = await params.client.request("users.prefs.get", {}); + if (this.preferenceScope !== params.scope) { + return; + } + if (result.status !== "ok") { + this.preferenceModeValue = "local"; + return; + } + let preferences = decodeIdentityPreferences(result.entries); + const browserPreferences = loadBrowserPreferences(params.gatewayUrl); + if (result.entries[PREFS_MIGRATION_KEY] !== true) { + const missingBrowserPreferences = Object.fromEntries( + Object.entries(browserPreferences).filter( + ([agentId]) => !Object.hasOwn(preferences, agentId), + ), + ); + const migrationEntries = [ + ...Object.entries(encodeIdentityPreferences(missingBrowserPreferences)), + [PREFS_MIGRATION_KEY, true] as const, + ]; + let migrationFailed = false; + for (let offset = 0; offset < migrationEntries.length; offset += 32) { + const batch = Object.fromEntries(migrationEntries.slice(offset, offset + 32)); + let response: UsersPrefsSetResult; + try { + response = await params.client.request("users.prefs.set", { + entries: batch, + }); + } catch { + migrationFailed = true; + break; + } + if (this.preferenceScope !== params.scope) { + return; + } + if (response.status !== "ok") { + migrationFailed = true; + break; + } + Object.assign(preferences, decodeIdentityPreferences(batch)); + } + if (migrationFailed) { + preferences = { ...browserPreferences, ...preferences }; + } + } + this.identityPreferences = preferences; + this.preferenceModeValue = "remote"; + for (const [agentId, preference] of Object.entries(preferences)) { + replaceBrowserPreference(params.gatewayUrl, agentId, preference); + } + if (this.read().agentsHydrated) { + this.callbacks.onAdoptAgentDefaults(); + } + this.callbacks.requestUpdate(); + } catch { + if (this.preferenceScope === params.scope) { + this.preferenceModeValue = "local"; + this.callbacks.requestUpdate(); + } + } + } +} diff --git a/ui/src/pages/new-session/draft-place-browser.test.ts b/ui/src/pages/new-session/draft-place-browser.test.ts new file mode 100644 index 000000000000..e2a0a955d082 --- /dev/null +++ b/ui/src/pages/new-session/draft-place-browser.test.ts @@ -0,0 +1,111 @@ +import type { ReactiveController, ReactiveControllerHost } from "lit"; +import { describe, expect, it, vi } from "vitest"; +import type { ApplicationContext } from "../../app/context.ts"; +import { DraftGatewayState } from "./draft-gateway-state.ts"; +import { DraftPlaceBrowser } from "./draft-place-browser.ts"; + +class ControllerHost implements ReactiveControllerHost { + readonly updateComplete = Promise.resolve(true); + addController(_controller: ReactiveController) {} + removeController(_controller: ReactiveController) {} + requestUpdate() {} +} + +function createBrowser(request: (method: string) => Promise) { + const host = new ControllerHost(); + const client = { request, recoveryScope: "principal-a", recoveryScopeReady: true }; + const context = { + gateway: { + connection: { gatewayUrl: "ws://gateway.example" }, + snapshot: { + phase: "connected", + client, + hello: { + auth: { role: "operator", scopes: ["operator.read"] }, + features: { methods: ["projects.list"] }, + }, + }, + }, + } as unknown as ApplicationContext; + const gateway = new DraftGatewayState( + host, + () => ({ + context, + data: undefined, + isConnected: true, + isAdmin: false, + canStartAsDraft: false, + visibility: "normal", + cloudProfileId: "", + pendingCloud: { sessionKey: "", gatewayUrl: "", recoveryScope: "" }, + agentsHydrated: false, + }), + { + requestUpdate: vi.fn(), + updateComplete: () => Promise.resolve(), + onInvalidate: vi.fn(), + onVisibilityRetired: vi.fn(), + onCloudProfileCleared: vi.fn(), + onCloudState: vi.fn(), + onPendingCloudReset: vi.fn(), + onRecoveryReady: vi.fn(), + onAdoptAgentDefaults: vi.fn(), + }, + ); + gateway.synchronize(context.gateway); + const browser = new DraftPlaceBrowser( + host, + gateway, + () => ({ + context, + projectId: "", + nodes: [], + folder: "", + execNode: "", + isAdmin: false, + }), + { + requestUpdate: vi.fn(), + onProjectMissing: vi.fn(), + onSelectProject: vi.fn(), + onApplyFolder: vi.fn(), + onApprovedListing: vi.fn(), + querySelector: () => null, + activeElement: () => null, + body: () => null, + }, + ); + return browser; +} + +describe("DraftPlaceBrowser", () => { + it.each([ + ["the Gateway omits recents", async () => ({ projects: [] })], + [ + "projects.list fails", + async () => { + throw new Error("projects unavailable"); + }, + ], + ])("keeps roster recents when %s", async (_label, request) => { + const browser = createBrowser(request); + + await browser.refreshProjects(); + + expect( + browser.resolveProjectRecents({ + sessions: [{ execCwd: "/workspace/recent" }], + workspace: "/workspace", + workspaceRoots: ["/workspace"], + execNodes: [], + isAdmin: false, + }), + ).toEqual([ + { + kind: "folder", + folder: "/workspace/recent", + displayName: "recent", + }, + ]); + }); +}); diff --git a/ui/src/pages/new-session/draft-place-browser.ts b/ui/src/pages/new-session/draft-place-browser.ts new file mode 100644 index 000000000000..f4d0bed00551 --- /dev/null +++ b/ui/src/pages/new-session/draft-place-browser.ts @@ -0,0 +1,596 @@ +import { initialState, Task, TaskStatus } from "@lit/task"; +import type { ReactiveControllerHost } from "lit"; +import type { + FsListDirResult, + ProjectRecord, + ProjectRecent, + ProjectsAddResult, + ProjectsListResult, + ProjectsRegisterResult, + ProjectsSearchRemoteResult, + WorktreesBranchesResult, +} from "../../../../packages/gateway-protocol/src/index.js"; +import type { ApplicationContext } from "../../app/context.ts"; +import { t } from "../../i18n/index.ts"; +import { canCallGatewayMethod, isGatewayMethodAdvertised } from "../../lib/gateway-methods.ts"; +import type { BrowserTarget, DraftNode } from "./discovery.ts"; +import type { DraftGatewayState } from "./draft-gateway-state.ts"; +import { folderDisplayName, isAbsolutePath, isKnownWorkspacePath } from "./path.ts"; +import { projectCloneInput } from "./place-picker.ts"; +import { recentPlaces, type RecentPlaceSource } from "./recent-places.ts"; + +const PROJECT_SEARCH_DEBOUNCE_MS = 300; + +type DraftPlaceBrowserSnapshot = Readonly<{ + context: ApplicationContext | undefined; + projectId: string; + nodes: readonly DraftNode[]; + folder: string; + execNode: string; + isAdmin: boolean; +}>; + +type DraftPlaceBrowserCallbacks = { + requestUpdate: () => void; + onProjectMissing: () => void; + onSelectProject: (projectId: string) => void; + onApplyFolder: (folder: string, execNode: string, gatewayApproved: boolean) => void; + onApprovedListing: (listing: FsListDirResult) => void; + querySelector: (selector: string) => Element | null; + activeElement: () => Element | null; + body: () => HTMLElement | null; +}; + +export class DraftPlaceBrowser { + private projectsValue: ProjectRecord[] = []; + private projectRecentsValue: ProjectRecent[] | undefined; + private projectQueryValue = ""; + private debouncedProjectQuery = ""; + private projectCloneBusyValue = false; + private projectCloneErrorValue: string | null = null; + private browserLoadingValue = false; + private browserErrorValue: string | null = null; + private browserListingValue: FsListDirResult | null = null; + private browserTargetValue: BrowserTarget | null = null; + private browserProjectPathValue: string | null = null; + private browserRegisteringValue = false; + private placePopoverOpenValue = false; + private placePopoverHidingValue = false; + // Live head input; absolute paths stay applicable even without fs.listDir. + private browserPathDraftValue = ""; + private browserRequestToken = 0; + private projectCloneRequestToken = 0; + private projectSearchTimer: ReturnType | undefined; + + private readonly projectsTask: Task; + private readonly projectSearchTask: Task; + + constructor( + host: ReactiveControllerHost, + private readonly gateway: DraftGatewayState, + private readonly read: () => DraftPlaceBrowserSnapshot, + private readonly callbacks: DraftPlaceBrowserCallbacks, + ) { + this.projectsTask = new Task(host, { + args: () => + [ + this.read().context && this.gateway.connected ? this.gateway.client : null, + isGatewayMethodAdvertised( + this.read().context?.gateway.snapshot ?? {}, + "projects.list", + ) === true, + this.gateway.connectionEpoch, + ] as const, + task: async ([client, advertised]) => { + if (!client || !advertised) { + return { projects: [] } as ProjectsListResult; + } + return await ( + client as NonNullable + ).request("projects.list", {}); + }, + onComplete: (result) => { + const projects = result.projects ?? []; + this.projectsValue = projects; + this.projectRecentsValue = result.recents; + if ( + this.read().projectId && + !projects.some((project) => project.id === this.read().projectId) + ) { + this.callbacks.onProjectMissing(); + } + this.callbacks.requestUpdate(); + }, + onError: () => { + this.projectsValue = []; + this.projectRecentsValue = undefined; + this.callbacks.onProjectMissing(); + this.callbacks.requestUpdate(); + }, + }); + this.projectSearchTask = new Task(host, { + args: () => + [ + this.read().context && this.gateway.connected ? this.gateway.client : null, + this.read().context + ? canCallGatewayMethod( + this.read().context?.gateway.snapshot, + "projects.searchRemote", + "operator.read", + ) + : false, + this.debouncedProjectQuery, + this.gateway.connectionEpoch, + ] as const, + task: ([client, advertised, query], { signal }) => { + if (!client || !advertised || query.length < 2 || projectCloneInput(query)) { + return initialState; + } + return client.request( + "projects.searchRemote", + { query }, + { signal }, + ); + }, + }); + } + + get projects(): readonly ProjectRecord[] { + return this.projectsValue; + } + + get projectRecents(): readonly ProjectRecent[] | undefined { + return this.projectRecentsValue; + } + + get projectQuery(): string { + return this.projectQueryValue; + } + + get projectSearchResult(): ProjectsSearchRemoteResult | null { + return this.projectSearchTask.status === TaskStatus.COMPLETE && + this.debouncedProjectQuery === this.projectQueryValue.trim() + ? (this.projectSearchTask.value ?? null) + : null; + } + + get projectSearchLoading(): boolean { + return ( + this.debouncedProjectQuery.length >= 2 && + this.debouncedProjectQuery === this.projectQueryValue.trim() && + this.projectSearchTask.status === TaskStatus.PENDING + ); + } + + get projectSearchError(): string | null { + if ( + this.projectSearchTask.status !== TaskStatus.ERROR || + this.debouncedProjectQuery !== this.projectQueryValue.trim() + ) { + return null; + } + const error = this.projectSearchTask.error; + return error instanceof Error ? error.message : String(error); + } + + get projectCloneBusy(): boolean { + return this.projectCloneBusyValue; + } + + get projectCloneError(): string | null { + return this.projectCloneErrorValue; + } + + get browserLoading(): boolean { + return this.browserLoadingValue; + } + + get browserError(): string | null { + return this.browserErrorValue; + } + + get browserListing(): FsListDirResult | null { + return this.browserListingValue; + } + + get browserTarget(): BrowserTarget | null { + return this.browserTargetValue; + } + + get browserProjectPath(): string | null { + return this.browserProjectPathValue; + } + + get browserRegistering(): boolean { + return this.browserRegisteringValue; + } + + get placePopoverOpen(): boolean { + return this.placePopoverOpenValue; + } + + get placePopoverHiding(): boolean { + return this.placePopoverHidingValue; + } + + get browserPathDraft(): string { + return this.browserPathDraftValue; + } + + set browserPathDraft(value: string) { + this.browserPathDraftValue = value; + this.callbacks.requestUpdate(); + } + + async refreshProjects(): Promise { + const context = this.read().context; + return await this.projectsTask.run([ + this.gateway.connected ? this.gateway.client : null, + context + ? isGatewayMethodAdvertised(context.gateway.snapshot, "projects.list") === true + : false, + this.gateway.connectionEpoch, + ]); + } + + selectedProject(projectId: string): ProjectRecord | undefined { + return this.projectsValue.find((project) => project.id === projectId); + } + + resolveProjectRecents(params: { + sessions: readonly RecentPlaceSource[]; + workspace: string; + workspaceRoots: readonly string[]; + execNodes: readonly DraftNode[]; + isAdmin: boolean; + }): ProjectRecent[] { + const allowGatewayFolder = (folder: string) => + params.isAdmin || isKnownWorkspacePath(params.workspaceRoots, folder); + const serverRecents = this.projectRecentsValue?.filter((recent) => + recent.kind === "project" + ? this.projectsValue.some((project) => project.id === recent.projectId) + : recent.execNode + ? params.execNodes.some((node) => node.nodeId === recent.execNode) + : allowGatewayFolder(recent.folder), + ); + return ( + serverRecents ?? + recentPlaces(params.sessions, { + workspace: params.workspace, + execNodes: params.execNodes, + allowGatewayFolder, + }).map((recent) => { + const item: ProjectRecent = { + kind: "folder", + folder: recent.folder, + displayName: folderDisplayName(recent.folder), + }; + if (recent.execNode) { + item.execNode = recent.execNode; + } + return item; + }) + ); + } + + changeProjectQuery(query: string) { + this.projectQueryValue = query; + this.projectCloneErrorValue = null; + this.clearProjectSearchTimer(); + this.debouncedProjectQuery = ""; + void this.projectSearchTask.run([null, false, "", this.gateway.connectionEpoch]); + const normalized = query.trim(); + const context = this.read().context; + if ( + normalized.length < 2 || + projectCloneInput(normalized) || + !this.gateway.connected || + !this.gateway.client || + !context || + !canCallGatewayMethod(context.gateway.snapshot, "projects.searchRemote", "operator.read") + ) { + this.callbacks.requestUpdate(); + return; + } + const client = this.gateway.client; + const connectionEpoch = this.gateway.connectionEpoch; + this.projectSearchTimer = globalThis.setTimeout(() => { + this.projectSearchTimer = undefined; + if (client !== this.gateway.client || connectionEpoch !== this.gateway.connectionEpoch) { + return; + } + this.debouncedProjectQuery = normalized; + void this.projectSearchTask.run([client, true, normalized, connectionEpoch]); + this.callbacks.requestUpdate(); + }, PROJECT_SEARCH_DEBOUNCE_MS); + this.callbacks.requestUpdate(); + } + + async addRemoteProject(gitUrl: string) { + const client = this.gateway.client; + const context = this.read().context; + if ( + !client || + !this.gateway.connected || + this.projectCloneBusyValue || + !context || + !canCallGatewayMethod(context.gateway.snapshot, "projects.add", "operator.write") + ) { + return; + } + const requestId = ++this.projectCloneRequestToken; + const connectionEpoch = this.gateway.connectionEpoch; + this.projectCloneBusyValue = true; + this.projectCloneErrorValue = null; + this.callbacks.requestUpdate(); + try { + const project = await client.request( + "projects.add", + { gitUrl }, + { timeoutMs: null }, + ); + if ( + requestId !== this.projectCloneRequestToken || + client !== this.gateway.client || + connectionEpoch !== this.gateway.connectionEpoch + ) { + return; + } + await this.projectsTask.run([client, true, connectionEpoch]); + if ( + requestId !== this.projectCloneRequestToken || + client !== this.gateway.client || + connectionEpoch !== this.gateway.connectionEpoch + ) { + return; + } + this.callbacks.onSelectProject(project.id); + this.close(); + } catch (error) { + if (requestId === this.projectCloneRequestToken && client === this.gateway.client) { + this.projectCloneErrorValue = error instanceof Error ? error.message : String(error); + } + } finally { + if (requestId === this.projectCloneRequestToken) { + this.projectCloneBusyValue = false; + this.callbacks.requestUpdate(); + } + } + } + + resetProjectSearch() { + this.clearProjectSearchTimer(); + this.projectCloneRequestToken += 1; + this.projectQueryValue = ""; + this.debouncedProjectQuery = ""; + this.projectCloneBusyValue = false; + this.projectCloneErrorValue = null; + this.callbacks.requestUpdate(); + } + + resetProjects() { + this.projectsValue = []; + this.projectRecentsValue = undefined; + this.resetProjectSearch(); + } + + close() { + this.resetBrowser(true); + const popover = this.callbacks.querySelector(".new-session-page__place-popover") as + | (HTMLElement & { + open: boolean; + }) + | null; + if (popover) { + popover.open = false; + } + } + + showRoot() { + this.resetBrowser(false); + } + + usableBrowserPath(): string | null { + const draft = this.browserPathDraftValue.trim(); + if (draft.length === 0) { + return ""; + } + return isAbsolutePath(draft) ? draft : null; + } + + selectBrowserTarget(target: BrowserTarget) { + const snapshot = this.read(); + const folder = snapshot.folder.trim(); + const matchesCurrentTarget = target.nodeId === snapshot.execNode; + const path = matchesCurrentTarget && isAbsolutePath(folder) ? folder : undefined; + this.browserTargetValue = target; + this.loadBrowser(path); + } + + loadBrowser(path: string | undefined) { + const snapshot = this.read(); + const gatewaySnapshot = snapshot.context?.gateway.snapshot; + const client = gatewaySnapshot?.client; + const target = this.browserTargetValue; + if (gatewaySnapshot?.phase !== "connected" || !client || !target) { + return; + } + const targetNode = snapshot.nodes.find((node) => node.nodeId === target.nodeId); + if (targetNode?.canExec && !targetNode.canBrowse) { + this.showRoot(); + this.browserTargetValue = target; + this.browserPathDraftValue = path ?? ""; + this.callbacks.requestUpdate(); + return; + } + const requestId = ++this.browserRequestToken; + this.browserLoadingValue = true; + this.browserErrorValue = null; + this.browserProjectPathValue = null; + this.browserListingValue = null; + this.browserPathDraftValue = path ?? ""; + const draftAtRequest = this.browserPathDraftValue; + this.callbacks.requestUpdate(); + void client + .request("fs.listDir", { + ...(path ? { path } : {}), + ...(target.nodeId ? { nodeId: target.nodeId } : {}), + }) + .then((result) => { + if (requestId !== this.browserRequestToken) { + return; + } + this.browserListingValue = result ?? null; + if (result) { + this.callbacks.onApprovedListing(result); + } + if (result?.path && this.browserPathDraftValue === draftAtRequest) { + this.browserPathDraftValue = result.path; + } + if (result?.path && !target.nodeId && snapshot.isAdmin) { + void client + .request("worktrees.branches", { + repoRoot: result.path, + includeRepositoryStatus: true, + }) + .then((branches) => { + if ( + requestId === this.browserRequestToken && + this.browserListingValue?.path === result.path && + branches.repositoryStatus === "git" + ) { + this.browserProjectPathValue = result.path; + this.callbacks.requestUpdate(); + } + }) + .catch(() => undefined); + } + this.callbacks.requestUpdate(); + }) + .catch(() => { + if (requestId !== this.browserRequestToken) { + return; + } + if (path) { + this.loadBrowser(undefined); + return; + } + this.browserErrorValue = t("newSession.browserLoadFailed"); + this.callbacks.requestUpdate(); + }) + .finally(() => { + if (requestId === this.browserRequestToken) { + this.browserLoadingValue = false; + this.callbacks.requestUpdate(); + } + }); + } + + async registerBrowserProject(path: string) { + const snapshot = this.read(); + const gatewaySnapshot = snapshot.context?.gateway.snapshot; + const client = gatewaySnapshot?.client; + if ( + gatewaySnapshot?.phase !== "connected" || + !client || + !snapshot.isAdmin || + this.browserTargetValue?.nodeId || + this.browserProjectPathValue !== path || + this.browserRegisteringValue + ) { + return; + } + const requestId = this.browserRequestToken; + const connectionEpoch = this.gateway.connectionEpoch; + this.browserRegisteringValue = true; + this.browserErrorValue = null; + this.callbacks.requestUpdate(); + try { + const project = await client.request("projects.register", { path }); + if (requestId !== this.browserRequestToken || client !== this.gateway.client) { + return; + } + await this.projectsTask.run([client, true, connectionEpoch]); + if (requestId !== this.browserRequestToken || client !== this.gateway.client) { + return; + } + this.callbacks.onSelectProject(project.id); + this.close(); + } catch (error) { + if (requestId === this.browserRequestToken && client === this.gateway.client) { + this.browserErrorValue = error instanceof Error ? error.message : String(error); + } + } finally { + if (requestId === this.browserRequestToken) { + this.browserRegisteringValue = false; + this.callbacks.requestUpdate(); + } + } + } + + onPopoverShow() { + this.placePopoverOpenValue = true; + this.showRoot(); + } + + onPopoverHide() { + this.placePopoverOpenValue = false; + this.placePopoverHidingValue = true; + this.showRoot(); + } + + onPopoverAfterHide() { + this.placePopoverHidingValue = false; + this.restorePopoverTrigger("new-session-place-trigger", ".new-session-page__place-popover"); + this.callbacks.requestUpdate(); + } + + guardPopoverTransition(event: Event) { + if (!this.placePopoverHidingValue) { + return; + } + event.preventDefault(); + event.stopImmediatePropagation(); + } + + clearPopoverHiding() { + this.placePopoverHidingValue = false; + this.callbacks.requestUpdate(); + } + + disconnect() { + this.clearProjectSearchTimer(); + void this.projectsTask.run([null, false, -1]); + void this.projectSearchTask.run([null, false, "", -1]); + } + + private resetBrowser(closePopover: boolean) { + this.browserRequestToken += 1; + this.browserLoadingValue = false; + this.browserErrorValue = null; + this.browserListingValue = null; + this.browserTargetValue = null; + this.browserProjectPathValue = null; + this.browserRegisteringValue = false; + this.browserPathDraftValue = ""; + if (closePopover) { + this.placePopoverOpenValue = false; + } + this.callbacks.requestUpdate(); + } + + private clearProjectSearchTimer() { + globalThis.clearTimeout(this.projectSearchTimer); + this.projectSearchTimer = undefined; + } + + private restorePopoverTrigger(id: string, popoverSelector: string) { + const active = this.callbacks.activeElement(); + const popover = this.callbacks.querySelector(popoverSelector); + const body = this.callbacks.body(); + if (active && active !== body && !popover?.contains(active)) { + return; + } + (this.callbacks.querySelector(`#${id}`) as HTMLButtonElement | null)?.focus(); + } +} diff --git a/ui/src/pages/new-session/draft-place-state.ts b/ui/src/pages/new-session/draft-place-state.ts new file mode 100644 index 000000000000..d198189e1a97 --- /dev/null +++ b/ui/src/pages/new-session/draft-place-state.ts @@ -0,0 +1,744 @@ +import type { + FsListDirResult, + WorktreesBranchesResult, +} from "../../../../packages/gateway-protocol/src/index.js"; +import type { ApplicationContext } from "../../app/context.ts"; +import { hasOperatorAdminAccess, hasOperatorWriteAccess } from "../../app/operator-access.ts"; +import { t } from "../../i18n/index.ts"; +import { listSelectableAgents } from "../../lib/agents/display.ts"; +import { normalizeAgentId } from "../../lib/sessions/session-key.ts"; +import { normalizeOptionalString } from "../../lib/string-coerce.ts"; +import * as catalog from "./catalog-target.ts"; +import type { DraftNode, DraftRepositoryState } from "./discovery.ts"; +import { readDraftNodes } from "./discovery.ts"; +import type { DraftGatewayState } from "./draft-gateway-state.ts"; +import type { DraftPlaceBrowser } from "./draft-place-browser.ts"; +import { isMissingRestoredFolderError } from "./folder-validation.ts"; +import type { NewSessionRouteData } from "./location.ts"; +import { newSessionSearch } from "./location.ts"; +import { NewSessionModelControl } from "./model-control.ts"; +import { isKnownWorkspacePath } from "./path.ts"; + +type DraftPlaceSnapshot = Readonly<{ + context: ApplicationContext | undefined; + data: NewSessionRouteData | undefined; + submitting: boolean; + pendingCloudSessionKey: string; +}>; + +type DraftPlaceCallbacks = { + requestUpdate: () => void; + onError: (error: string | null) => void; + onClearError: (error: string) => void; +}; + +export class DraftPlaceState { + private agentIdValue = ""; + private folderValue = ""; + private projectIdValue = ""; + private worktreeValue = false; + private worktreeNameValue = ""; + private baseRefValue = ""; + private repositoryValue: DraftRepositoryState = { kind: "idle" }; + private nodesValue: DraftNode[] = []; + private execNodeValue = ""; + private cloudProfileIdValue = ""; + private restoredFolderValidation: "none" | "checking" | "failed" = "none"; + private gatewayApprovedWorkspaceRoots: string[] = []; + private agentsHydratedValue = false; + private nodesHydrated = false; + private agentSelectedByUser = false; + private folderSelectedByUser = false; + private folderGatewayApproved = false; + private preferredWorktreeRestore = false; + private worktreeSelectedByUser = false; + private nodesRequestToken = 0; + private branchesRequestToken = 0; + private baseRefEditGeneration = 0; + private restoredFolderValidationToken = 0; + + readonly modelControl: NewSessionModelControl; + + constructor( + private readonly gateway: DraftGatewayState, + readonly browser: DraftPlaceBrowser, + private readonly read: () => DraftPlaceSnapshot, + private readonly callbacks: DraftPlaceCallbacks, + ) { + this.modelControl = new NewSessionModelControl( + callbacks.requestUpdate, + (selection) => this.persistPreference(selection), + (catalogId) => + this.read().context?.navigate("new-session", { + search: newSessionSearch(this.agentIdValue, { catalogId }), + }), + ); + } + + get agentId(): string { + return this.agentIdValue; + } + + get folder(): string { + return this.folderValue; + } + + get projectId(): string { + return this.projectIdValue; + } + + get worktree(): boolean { + return this.worktreeValue; + } + + get worktreeName(): string { + return this.worktreeNameValue; + } + + get baseRef(): string { + return this.baseRefValue; + } + + get repository(): DraftRepositoryState { + return this.repositoryValue; + } + + get nodes(): readonly DraftNode[] { + return this.nodesValue; + } + + get execNode(): string { + return this.execNodeValue; + } + + get cloudProfileId(): string { + return this.cloudProfileIdValue; + } + + get agentsHydrated(): boolean { + return this.agentsHydratedValue; + } + + get worktreePreferenceReady(): boolean { + return !this.preferredWorktreeRestore; + } + + setAgentsHydrated(value: boolean) { + this.agentsHydratedValue = value; + } + + agents() { + return listSelectableAgents(this.read().context?.agents.state.agentsList?.agents ?? []); + } + + selectedAgent() { + const agentId = normalizeAgentId(this.agentIdValue); + return this.agents().find((agent) => normalizeAgentId(agent.id) === agentId); + } + + selectedProject() { + return this.browser.selectedProject(this.projectIdValue); + } + + execNodes(): DraftNode[] { + return this.nodesValue.filter((node) => node.canExec); + } + + execNodeReady(): boolean { + return ( + !this.execNodeValue || + (this.nodesHydrated && this.execNodes().some((node) => node.nodeId === this.execNodeValue)) + ); + } + + isAdmin(): boolean { + return hasOperatorAdminAccess(this.read().context?.gateway.snapshot.hello?.auth ?? null); + } + + canWrite(): boolean { + return hasOperatorWriteAccess(this.read().context?.gateway.snapshot.hello?.auth ?? null); + } + + workspacePath(): string { + return normalizeOptionalString(this.selectedAgent()?.workspace) ?? ""; + } + + knownWorkspaceRoots(): string[] { + const configuredWorkspace = this.workspacePath(); + return configuredWorkspace + ? [configuredWorkspace, ...this.gatewayApprovedWorkspaceRoots] + : this.gatewayApprovedWorkspaceRoots; + } + + recordGatewayApprovedListing(listing: FsListDirResult) { + if (this.isAdmin()) { + return; + } + const roots = new Set(this.gatewayApprovedWorkspaceRoots); + roots.add(listing.path); + if (listing.parent) { + roots.add(listing.parent); + } + if (roots.size !== this.gatewayApprovedWorkspaceRoots.length) { + this.gatewayApprovedWorkspaceRoots = [...roots]; + this.callbacks.requestUpdate(); + } + } + + folderSubmissionBlocked(): boolean { + if (this.projectIdValue) { + return !this.selectedProject(); + } + if (this.restoredFolderValidation !== "none") { + return true; + } + if ( + !this.usesCustomFolder() || + this.isAdmin() || + this.folderGatewayApproved || + isKnownWorkspacePath(this.knownWorkspaceRoots(), this.folderValue) + ) { + return false; + } + // Free-typed paths still reach sessions.create so the Gateway can return + // the authoritative missing-scope error instead of the UI dead-ending. + return false; + } + + adoptAgentDefaults( + options: { preserveSelectedAgent?: boolean; preserveSelectedFolder?: boolean } = {}, + ) { + const snapshot = this.read(); + const agents = this.agents(); + const configuredDefault = snapshot.context?.agents.state.agentsList?.defaultId; + const fallback = agents.some((agent) => agent.id === configuredDefault) + ? (configuredDefault ?? "main") + : (agents[0]?.id ?? "main"); + const keepSelectedAgent = + options.preserveSelectedAgent && this.agentSelectedByUser && Boolean(this.selectedAgent()); + if (!keepSelectedAgent) { + this.agentIdValue = catalog.resolveAgentId(snapshot.data, agents, fallback); + this.agentSelectedByUser = false; + } + const preference = this.gateway.readPreference(this.agentIdValue); + const keepSelectedFolder = options.preserveSelectedFolder && this.folderSelectedByUser; + if (!this.execNodeValue && !keepSelectedFolder && !snapshot.pendingCloudSessionKey) { + const workspace = this.workspacePath(); + const storedFolder = preference?.folder ?? ""; + const storedWorkspaceMoved = + Boolean(storedFolder) && + storedFolder === preference?.workspace && + preference.workspace !== workspace; + const storedFolderUsable = Boolean(storedFolder) && !storedWorkspaceMoved; + this.folderValue = storedFolderUsable ? storedFolder : workspace; + this.folderGatewayApproved = false; + this.folderSelectedByUser = false; + this.preferredWorktreeRestore = preference?.worktree === true; + this.worktreeSelectedByUser = false; + if (storedWorkspaceMoved) { + this.persistPreference({ folder: workspace }); + } + } + if ( + keepSelectedFolder && + !this.execNodeValue && + !snapshot.pendingCloudSessionKey && + this.agentIdValue + ) { + this.persistPreference({ folder: this.folderValue, worktree: this.worktreeValue }); + } + void this.loadNodes(); + this.modelControl.load(snapshot.context, this.agentIdValue, !catalog.isTarget(snapshot.data), { + agent: this.selectedAgent(), + preference, + }); + if ( + !this.folderSelectedByUser && + this.folderValue !== this.workspacePath() && + !this.execNodeValue && + !snapshot.pendingCloudSessionKey + ) { + this.validateRestoredFolder(this.folderValue); + } else { + this.cancelRestoredFolderValidation(); + this.maybeLoadBranches(); + } + this.callbacks.requestUpdate(); + } + + resetDraft() { + this.agentSelectedByUser = false; + this.folderValue = ""; + this.projectIdValue = ""; + this.browser.resetProjectSearch(); + this.folderSelectedByUser = false; + this.folderGatewayApproved = false; + this.gatewayApprovedWorkspaceRoots = []; + this.cancelRestoredFolderValidation(); + this.preferredWorktreeRestore = false; + this.worktreeSelectedByUser = false; + this.worktreeValue = false; + this.worktreeNameValue = ""; + this.baseRefValue = ""; + this.repositoryValue = { kind: "idle" }; + this.execNodeValue = ""; + this.modelControl.reset(); + this.cloudProfileIdValue = ""; + this.callbacks.requestUpdate(); + } + + invalidateGatewayDiscovery(resetHostSelection: boolean) { + this.nodesRequestToken += 1; + this.nodesHydrated = false; + this.branchesRequestToken += 1; + this.repositoryValue = { kind: "idle" }; + this.baseRefValue = ""; + this.agentsHydratedValue = false; + this.modelControl.invalidate(resetHostSelection); + this.browser.close(); + this.cancelRestoredFolderValidation(); + this.gatewayApprovedWorkspaceRoots = []; + this.folderGatewayApproved = false; + this.browser.resetProjectSearch(); + if (!resetHostSelection) { + this.callbacks.requestUpdate(); + return; + } + this.agentIdValue = ""; + this.agentSelectedByUser = false; + this.folderValue = ""; + this.browser.resetProjects(); + this.projectIdValue = ""; + this.folderSelectedByUser = false; + this.preferredWorktreeRestore = false; + this.worktreeSelectedByUser = false; + this.worktreeValue = false; + this.worktreeNameValue = ""; + this.baseRefEditGeneration += 1; + this.nodesValue = []; + this.execNodeValue = ""; + this.cloudProfileIdValue = ""; + this.callbacks.requestUpdate(); + } + + applyPendingCloud(params: { agentId: string; profileId: string; cwd?: string }) { + this.agentIdValue = params.agentId; + this.cloudProfileIdValue = params.profileId; + this.worktreeValue = true; + this.folderValue = params.cwd ?? ""; + this.folderGatewayApproved = false; + this.callbacks.requestUpdate(); + } + + clearCloudProfile() { + this.cloudProfileIdValue = ""; + this.browser.close(); + this.callbacks.requestUpdate(); + } + + clearProjectSelection() { + this.projectIdValue = ""; + this.maybeLoadBranches(); + this.callbacks.requestUpdate(); + } + + selectAgentId(agentId: string) { + const snapshot = this.read(); + if (snapshot.submitting || snapshot.pendingCloudSessionKey || catalog.isTarget(snapshot.data)) { + return; + } + if (normalizeAgentId(agentId) === normalizeAgentId(this.agentIdValue)) { + return; + } + this.agentIdValue = normalizeAgentId(agentId); + this.cancelRestoredFolderValidation(); + this.modelControl.reset(); + this.callbacks.onError(null); + this.agentSelectedByUser = true; + this.folderSelectedByUser = false; + this.folderGatewayApproved = false; + this.gatewayApprovedWorkspaceRoots = []; + this.projectIdValue = ""; + this.preferredWorktreeRestore = false; + this.worktreeSelectedByUser = false; + this.cloudProfileIdValue = ""; + this.worktreeValue = false; + this.worktreeNameValue = ""; + this.browser.close(); + if (this.execNodeValue) { + this.folderValue = ""; + } + this.adoptAgentDefaults({ preserveSelectedAgent: true }); + } + + applyFolder(folder: string, execNode = this.execNodeValue, gatewayApproved = false) { + const snapshot = this.read(); + if (snapshot.submitting || snapshot.pendingCloudSessionKey) { + return; + } + this.execNodeValue = execNode; + this.projectIdValue = ""; + this.cancelRestoredFolderValidation(); + if (execNode) { + this.cloudProfileIdValue = ""; + } + this.callbacks.onError(null); + this.folderValue = folder.trim(); + this.folderGatewayApproved = gatewayApproved && !execNode && !this.isAdmin(); + this.folderSelectedByUser = true; + this.preferredWorktreeRestore = false; + this.worktreeSelectedByUser = true; + if (this.execNodeValue || !this.cloudProfileIdValue) { + this.worktreeValue = false; + } + this.worktreeNameValue = ""; + if (!this.execNodeValue && this.agentsHydratedValue) { + this.persistPreference({ folder: this.folderValue, worktree: this.worktreeValue }); + } + this.maybeLoadBranches(); + } + + selectProjectId(projectId: string) { + const snapshot = this.read(); + if (snapshot.submitting || snapshot.pendingCloudSessionKey) { + return; + } + const project = this.browser.selectedProject(projectId); + if (!project) { + return; + } + this.cancelRestoredFolderValidation(); + this.browser.resetProjectSearch(); + this.projectIdValue = project.id; + this.execNodeValue = ""; + this.cloudProfileIdValue = ""; + this.callbacks.onError(null); + this.folderSelectedByUser = false; + this.preferredWorktreeRestore = false; + this.worktreeSelectedByUser = true; + this.worktreeValue = false; + this.worktreeNameValue = ""; + this.maybeLoadBranches(); + } + + selectExecNode(execNode: string) { + const snapshot = this.read(); + if (snapshot.submitting || snapshot.pendingCloudSessionKey) { + return; + } + if (execNode === this.execNodeValue && !this.cloudProfileIdValue) { + return; + } + const keepGatewayFolder = !execNode && !this.execNodeValue; + this.cancelRestoredFolderValidation(); + const keepWorktree = keepGatewayFolder && this.worktreeValue && this.worktreeAvailable(); + this.execNodeValue = execNode; + this.cloudProfileIdValue = ""; + if (!keepGatewayFolder) { + this.folderValue = execNode ? "" : this.workspacePath(); + this.folderSelectedByUser = false; + this.folderGatewayApproved = false; + this.projectIdValue = ""; + } + this.worktreeValue = keepWorktree; + this.browser.close(); + if (!this.branchesMatchCurrentRepo()) { + this.maybeLoadBranches(); + } + this.callbacks.requestUpdate(); + } + + selectCloudProfile(profileId: string) { + const snapshot = this.read(); + if ( + snapshot.submitting || + snapshot.pendingCloudSessionKey || + !this.worktreeAvailable() || + !this.gateway.cloudProfiles.some((profile) => profile.id === profileId) + ) { + return; + } + this.cloudProfileIdValue = profileId; + this.projectIdValue = ""; + this.callbacks.onError(null); + this.worktreeValue = true; + this.browser.close(); + if (!this.branchesMatchCurrentRepo()) { + this.maybeLoadBranches(); + } + this.callbacks.requestUpdate(); + } + + toggleWorktree() { + if (this.cloudProfileIdValue) { + return; + } + this.worktreeValue = !this.worktreeValue; + this.preferredWorktreeRestore = false; + this.worktreeSelectedByUser = true; + this.persistPreference({ + folder: this.folderValue.trim() || this.workspacePath(), + worktree: this.worktreeValue, + }); + if (this.worktreeValue && this.repositoryValue.kind !== "git") { + this.maybeLoadBranches(); + } + this.callbacks.requestUpdate(); + } + + setBaseRef(baseRef: string) { + if (!this.read().submitting) { + this.baseRefEditGeneration += 1; + this.baseRefValue = baseRef; + this.callbacks.requestUpdate(); + } + } + + setWorktreeName(worktreeName: string) { + if (!this.read().submitting) { + this.worktreeNameValue = worktreeName; + this.callbacks.requestUpdate(); + } + } + + browseAvailable(): boolean { + return this.gateway.connected && (this.isAdmin() || Boolean(this.workspacePath())); + } + + worktreeAvailable(): boolean { + if (this.execNodeValue) { + return false; + } + if (this.selectedProject()?.repoRoot) { + return true; + } + if (this.repositoryValue.kind === "git") { + return true; + } + return ( + this.repositoryValue.kind === "unavailable" && + this.repositoryValue.repoRoot === this.workspacePath() && + this.selectedAgent()?.workspaceGit === true + ); + } + + private usesCustomFolder(): boolean { + if (this.projectIdValue) { + return false; + } + const folder = this.folderValue.trim(); + return Boolean(folder) && folder !== this.workspacePath(); + } + + private persistPreference(patch: Parameters[2]) { + this.gateway.persistPreference(this.agentIdValue, this.workspacePath(), patch); + } + + private cancelRestoredFolderValidation() { + this.restoredFolderValidationToken += 1; + this.restoredFolderValidation = "none"; + } + + private restoreWorkspaceFolder() { + this.restoredFolderValidation = "none"; + this.folderGatewayApproved = false; + this.callbacks.onClearError(t("newSession.browserLoadFailed")); + this.folderValue = this.workspacePath(); + this.worktreeValue = false; + this.preferredWorktreeRestore = false; + this.persistPreference({ folder: this.folderValue, worktree: false }); + this.maybeLoadBranches(); + } + + private validateRestoredFolder(folder: string) { + const snapshot = this.read().context?.gateway.snapshot; + const client = snapshot?.client; + if (snapshot?.phase !== "connected" || !client) { + this.restoreWorkspaceFolder(); + return; + } + const requestId = ++this.restoredFolderValidationToken; + this.restoredFolderValidation = "checking"; + void client + .request("fs.listDir", { path: folder }) + .then((result) => { + if ( + requestId !== this.restoredFolderValidationToken || + this.folderSelectedByUser || + this.folderValue !== folder + ) { + return; + } + this.recordGatewayApprovedListing(result); + this.folderGatewayApproved = !this.isAdmin(); + this.restoredFolderValidation = "none"; + this.callbacks.onClearError(t("newSession.browserLoadFailed")); + this.maybeLoadBranches(); + }) + .catch((error: unknown) => { + if ( + requestId !== this.restoredFolderValidationToken || + this.folderSelectedByUser || + this.folderValue !== folder + ) { + return; + } + if (!this.isAdmin() || isMissingRestoredFolderError(error)) { + this.restoreWorkspaceFolder(); + return; + } + this.restoredFolderValidation = "failed"; + this.callbacks.onError(t("newSession.browserLoadFailed")); + }); + } + + private async loadNodes() { + const requestId = ++this.nodesRequestToken; + this.nodesHydrated = false; + const snapshot = this.read().context?.gateway.snapshot; + const client = snapshot?.client; + if (snapshot?.phase !== "connected" || !client || !this.isAdmin()) { + this.nodesValue = []; + this.nodesHydrated = true; + this.callbacks.requestUpdate(); + return; + } + try { + const result = await client.request<{ nodes?: unknown }>("node.list", {}); + if (requestId !== this.nodesRequestToken) { + return; + } + const nodes = readDraftNodes(result?.nodes); + this.nodesValue = nodes; + this.nodesHydrated = true; + if ( + this.execNodeValue && + !nodes.some((node) => node.nodeId === this.execNodeValue && node.canExec) + ) { + this.execNodeValue = ""; + this.folderValue = this.workspacePath(); + this.folderSelectedByUser = false; + this.folderGatewayApproved = false; + this.worktreeValue = false; + this.worktreeNameValue = ""; + this.browser.close(); + this.maybeLoadBranches(); + } + this.callbacks.requestUpdate(); + } catch { + if (requestId === this.nodesRequestToken) { + this.nodesValue = []; + this.nodesHydrated = true; + this.callbacks.requestUpdate(); + } + } + } + + private maybeLoadBranches() { + const requestId = ++this.branchesRequestToken; + const restoreWorktree = this.preferredWorktreeRestore && !this.worktreeSelectedByUser; + const baseRefEditGeneration = this.baseRefEditGeneration; + this.repositoryValue = { kind: "idle" }; + this.baseRefValue = ""; + const selectedProject = this.selectedProject(); + if (this.execNodeValue) { + this.preferredWorktreeRestore = false; + return; + } + if (selectedProject && !selectedProject.repoRoot) { + this.preferredWorktreeRestore = false; + return; + } + const repoRoot = selectedProject?.repoRoot ?? (this.folderValue.trim() || this.workspacePath()); + const agent = this.selectedAgent(); + const usesWorkspace = !selectedProject && repoRoot === this.workspacePath(); + if (!repoRoot) { + this.preferredWorktreeRestore = false; + return; + } + if (usesWorkspace && agent?.workspaceGit !== true) { + this.repositoryValue = { kind: "direct", repoRoot }; + const rejectedWorktree = !this.cloudProfileIdValue && (this.worktreeValue || restoreWorktree); + if (!this.cloudProfileIdValue) { + this.worktreeValue = false; + } + this.preferredWorktreeRestore = false; + if (rejectedWorktree) { + this.persistPreference({ worktree: false }); + } + return; + } + const snapshot = this.read().context?.gateway.snapshot; + const client = snapshot?.client; + if (snapshot?.phase !== "connected" || !client) { + this.preferredWorktreeRestore = false; + return; + } + this.repositoryValue = { kind: "checking", repoRoot }; + void client + .request("worktrees.branches", { + repoRoot, + includeRepositoryStatus: true, + }) + .then((result) => { + if (requestId !== this.branchesRequestToken) { + return; + } + if (result?.repositoryStatus !== "git") { + this.repositoryValue = { + kind: result?.repositoryStatus === "not_git" ? "direct" : "unavailable", + repoRoot, + }; + if (result?.repositoryStatus === "not_git") { + const rejectedWorktree = + !this.cloudProfileIdValue && (this.worktreeValue || restoreWorktree); + if (!this.cloudProfileIdValue) { + this.worktreeValue = false; + } + if (rejectedWorktree) { + this.persistPreference({ worktree: false }); + } + } else if (restoreWorktree && !this.worktreeSelectedByUser && this.worktreeAvailable()) { + this.worktreeValue = true; + } + this.preferredWorktreeRestore = false; + this.callbacks.requestUpdate(); + return; + } + this.repositoryValue = { + kind: "git", + repoRoot, + branches: result.branches, + ...(result.defaultBranch ? { defaultBranch: result.defaultBranch } : {}), + ...(result.headBranch ? { headBranch: result.headBranch } : {}), + }; + if (restoreWorktree && !this.worktreeSelectedByUser && !this.execNodeValue) { + this.worktreeValue = true; + } + this.preferredWorktreeRestore = false; + if (baseRefEditGeneration === this.baseRefEditGeneration) { + this.baseRefValue = result.defaultBranch ?? result.headBranch ?? ""; + } + this.callbacks.requestUpdate(); + }) + .catch(() => { + if (requestId !== this.branchesRequestToken) { + return; + } + this.repositoryValue = { kind: "unavailable", repoRoot }; + if (restoreWorktree && !this.worktreeSelectedByUser && this.worktreeAvailable()) { + this.worktreeValue = true; + } + this.preferredWorktreeRestore = false; + this.callbacks.requestUpdate(); + }); + } + + private branchesMatchCurrentRepo(): boolean { + if (this.execNodeValue || this.repositoryValue.kind === "idle") { + return false; + } + const repoRoot = this.folderValue.trim() || this.workspacePath(); + return this.repositoryValue.repoRoot === repoRoot; + } +} diff --git a/ui/src/pages/new-session/draft-submission-flow.test.ts b/ui/src/pages/new-session/draft-submission-flow.test.ts new file mode 100644 index 000000000000..2476967ca9bb --- /dev/null +++ b/ui/src/pages/new-session/draft-submission-flow.test.ts @@ -0,0 +1,205 @@ +import type { ReactiveController, ReactiveControllerHost } from "lit"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { ApplicationContext } from "../../app/context.ts"; +import { buildDraftSessionCreateParams } from "./create-params.ts"; +import { DraftGatewayState } from "./draft-gateway-state.ts"; +import { DraftPlaceBrowser } from "./draft-place-browser.ts"; +import { DraftPlaceState } from "./draft-place-state.ts"; +import { DraftSubmissionFlow } from "./draft-submission-flow.ts"; + +class ControllerHost implements ReactiveControllerHost { + readonly updateComplete = Promise.resolve(true); + addController(_controller: ReactiveController) {} + removeController(_controller: ReactiveController) {} + requestUpdate() {} +} + +afterEach(() => { + sessionStorage.clear(); +}); + +describe("DraftSubmissionFlow", () => { + it("hands cloud startup to the application owner and navigates immediately", async () => { + const createResult = vi.fn(async (params: Record) => ({ + key: String(params.key), + initialRun: { status: "idle" as const }, + })); + const start = vi.fn( + (_input: Parameters[0]) => + new Promise(() => { + // Application-owned startup intentionally outlives this route. + }), + ); + const navigate = vi.fn(); + const setSessionKey = vi.fn(); + const selectAgent = vi.fn(); + const client = { + recoveryScope: "principal-a", + recoveryScopeReady: true, + request: vi.fn(async (method: string) => { + if (method === "node.list") { + return { nodes: [] }; + } + if (method === "worktrees.branches") { + return { repositoryStatus: "git", branches: [] }; + } + return {}; + }), + }; + const context = { + basePath: "", + gateway: { + connection: { gatewayUrl: "ws://gateway.example" }, + snapshot: { + phase: "connected", + client, + hello: { + auth: { + role: "operator", + scopes: ["operator.read", "operator.write", "operator.admin"], + }, + features: { methods: ["sessions.create", "sessions.dispatch"] }, + }, + }, + setSessionKey, + }, + agents: { + state: { + connected: true, + client, + agentsList: { + defaultId: "cloud", + mainKey: "main", + agents: [{ id: "cloud", workspace: "/workspace", workspaceGit: true }], + }, + }, + }, + agentSelection: { state: { selectedId: "cloud" }, set: selectAgent }, + sessions: { state: { result: null }, createResult }, + cloudStartup: { start }, + config: { current: {} }, + navigate, + } as unknown as ApplicationContext; + const host = new ControllerHost(); + const gateway = new DraftGatewayState( + host, + () => ({ + context, + data: undefined, + isConnected: true, + isAdmin: place?.isAdmin() ?? true, + canStartAsDraft: flow?.canStartAsDraft() ?? false, + visibility: flow?.visibility ?? "normal", + cloudProfileId: place?.cloudProfileId ?? "", + pendingCloud: flow?.pendingCloud ?? { + sessionKey: "", + gatewayUrl: "", + recoveryScope: "", + }, + agentsHydrated: place?.agentsHydrated ?? false, + }), + { + requestUpdate: vi.fn(), + updateComplete: () => Promise.resolve(), + onInvalidate: vi.fn(), + onVisibilityRetired: () => flow?.setVisibility("normal"), + onCloudProfileCleared: () => place?.clearCloudProfile(), + onCloudState: (error) => flow?.setError(error), + onPendingCloudReset: () => flow?.resetPendingCloudWithoutClearingStorage(), + onRecoveryReady: (gatewayUrl, recoveryScope) => + flow?.restorePendingCloudRecovery(gatewayUrl, recoveryScope), + onAdoptAgentDefaults: () => place?.adoptAgentDefaults(), + }, + ); + const browser = new DraftPlaceBrowser( + host, + gateway, + () => ({ + context, + projectId: place?.projectId ?? "", + nodes: place?.nodes ?? [], + folder: place?.folder ?? "", + execNode: place?.execNode ?? "", + isAdmin: place?.isAdmin() ?? true, + }), + { + requestUpdate: vi.fn(), + onProjectMissing: () => place?.clearProjectSelection(), + onSelectProject: (projectId) => place?.selectProjectId(projectId), + onApplyFolder: (folder, execNode, approved) => + place?.applyFolder(folder, execNode, approved), + onApprovedListing: (listing) => place?.recordGatewayApprovedListing(listing), + querySelector: () => null, + activeElement: () => null, + body: () => null, + }, + ); + const place = new DraftPlaceState( + gateway, + browser, + () => ({ + context, + data: undefined, + submitting: flow?.submitting ?? false, + pendingCloudSessionKey: flow?.pendingCloud.sessionKey ?? "", + }), + { + requestUpdate: vi.fn(), + onError: (error) => flow?.setError(error), + onClearError: (error) => flow?.clearErrorIf(error), + }, + ); + const flow = new DraftSubmissionFlow( + gateway, + place, + () => ({ context, data: undefined, isConnected: true }), + { requestUpdate: vi.fn(), closeTransientUi: vi.fn() }, + ); + gateway.synchronize(context.gateway); + place.setAgentsHydrated(true); + place.adoptAgentDefaults(); + const apiAttachments = [{ fileName: "note.txt", content: "SGk=" }]; + const createParams = buildDraftSessionCreateParams({ + agentId: "cloud", + message: "", + worktree: true, + cwd: "/workspace", + workspace: "/workspace", + }); + flow.pendingCloud.stageCreate({ + agentId: "cloud", + profileId: "aws", + message: "keep this cloud task", + attachments: apiAttachments, + gatewayUrl: "ws://gateway.example", + recoveryScope: "principal-a", + createParams, + }); + flow.pendingCloud.retryAllowed = true; + place.applyPendingCloud({ agentId: "cloud", profileId: "aws", cwd: "/workspace" }); + flow.attachmentDraft.replace([ + { + id: "attachment-1", + dataUrl: "data:text/plain;base64,SGk=", + mimeType: "text/plain", + fileName: "note.txt", + }, + ]); + + await flow.submit(); + + expect(start).toHaveBeenCalledOnce(); + expect(start.mock.calls[0]?.[0].recovery).toMatchObject({ + message: "keep this cloud task", + attachments: apiAttachments, + phase: "dispatching", + }); + expect(flow.pendingCloud.capture()).toBeNull(); + expect(flow.attachmentDraft.attachments).toHaveLength(0); + expect(flow.submitting).toBe(false); + expect(createResult).toHaveBeenCalledOnce(); + expect(setSessionKey).toHaveBeenCalledWith(start.mock.calls[0]?.[0].recovery.sessionKey); + expect(selectAgent).toHaveBeenCalledWith("cloud"); + expect(navigate).toHaveBeenCalledOnce(); + }); +}); diff --git a/ui/src/pages/new-session/draft-submission-flow.ts b/ui/src/pages/new-session/draft-submission-flow.ts new file mode 100644 index 000000000000..91270d9768bf --- /dev/null +++ b/ui/src/pages/new-session/draft-submission-flow.ts @@ -0,0 +1,690 @@ +import type { SessionsCatalogStartTerminalResult } from "../../../../packages/gateway-protocol/src/index.js"; +import { selectApplicationSession } from "../../app/agent-selection.ts"; +import type { ApplicationContext } from "../../app/context.ts"; +import { t } from "../../i18n/index.ts"; +import { + readSessionMethodAccess, + type SessionMethodAccess, +} from "../../lib/session-method-access.ts"; +import { openTerminalSessionInTerminal } from "../../lib/sessions/catalog-terminal.ts"; +import type { CloudSessionRecovery } from "../../lib/sessions/cloud-recovery.ts"; +import { deleteCloudDraftSession } from "../../lib/sessions/cloud-startup.ts"; +import { sessionNavigationTarget } from "../../lib/sessions/route-navigation.ts"; +import { normalizeAgentId } from "../../lib/sessions/session-key.ts"; +import { isTerminalAvailable } from "../../lib/terminal-availability.ts"; +import { createManagedWorktree } from "../../lib/worktrees/create-worktree.ts"; +import { buildChatApiAttachments, restoreChatApiAttachments } from "../chat/attachment-api.ts"; +import { requiresChatModelSetup } from "../chat/chat-model-setup.ts"; +import { prepareInitialUserMessageHandoff } from "../chat/initial-turn-handoff.ts"; +import { NewSessionAttachmentDraft } from "./attachment-draft.ts"; +import * as catalog from "./catalog-target.ts"; +import { PendingCloudRecoveryState, type SubmissionOutcomeReason } from "./cloud-recovery-state.ts"; +import { NewSessionComposerTextareaController } from "./composer.ts"; +import { + buildDraftSessionCreateParams as assembleDraftSessionCreateParams, + canStartSessionAsDraft, + isWorktreeNameValid, + type NewSessionVisibility, +} from "./create-params.ts"; +import type { DraftGatewayState } from "./draft-gateway-state.ts"; +import type { DraftPlaceState } from "./draft-place-state.ts"; +import type { NewSessionRouteData } from "./location.ts"; +import { retainRejectedInitialTurn } from "./rejected-initial-turn.ts"; + +type DraftSubmissionSnapshot = Readonly<{ + context: ApplicationContext | undefined; + data: NewSessionRouteData | undefined; + isConnected: boolean; +}>; + +type DraftSubmissionCallbacks = { + requestUpdate: () => void; + closeTransientUi: () => void; +}; + +export class DraftSubmissionFlow { + private visibilityValue: NewSessionVisibility = "normal"; + private messageValue = ""; + private submittingValue = false; + private submissionOutcomeUnknownValue: SubmissionOutcomeReason | null = null; + private errorValue: string | null = null; + private submitRequestToken = 0; + readonly pendingCloud = new PendingCloudRecoveryState(); + readonly attachmentDraft: NewSessionAttachmentDraft; + readonly composerTextarea = new NewSessionComposerTextareaController(); + + constructor( + private readonly gateway: DraftGatewayState, + private readonly place: DraftPlaceState, + private readonly read: () => DraftSubmissionSnapshot, + private readonly callbacks: DraftSubmissionCallbacks, + ) { + this.attachmentDraft = new NewSessionAttachmentDraft(callbacks.requestUpdate); + } + + get visibility(): NewSessionVisibility { + return this.visibilityValue; + } + + get message(): string { + return this.messageValue; + } + + get submitting(): boolean { + return this.submittingValue; + } + + get submissionOutcomeUnknown(): SubmissionOutcomeReason | null { + return this.submissionOutcomeUnknownValue; + } + + get error(): string | null { + return this.errorValue; + } + + setMessage(message: string) { + this.messageValue = message; + this.callbacks.requestUpdate(); + } + + setVisibility(visibility: NewSessionVisibility) { + this.visibilityValue = visibility; + this.callbacks.requestUpdate(); + } + + setError(error: string | null) { + if (error === null && this.errorValue === t("newSession.cloudRecoveryUnavailable")) { + this.errorValue = null; + } else if (error !== null) { + this.errorValue = error; + } + this.callbacks.requestUpdate(); + } + + clearError() { + this.errorValue = null; + this.callbacks.requestUpdate(); + } + + clearErrorIf(error: string) { + if (this.errorValue === error) { + this.errorValue = null; + this.callbacks.requestUpdate(); + } + } + + markPendingCloudUnavailable(outcome: SubmissionOutcomeReason) { + this.pendingCloud.retryAllowed = false; + this.submissionOutcomeUnknownValue = outcome; + this.callbacks.requestUpdate(); + } + + canStartAsDraft(): boolean { + return canStartSessionAsDraft({ + allowedVisibilities: + this.read().context?.gateway.snapshot.hello?.policy?.allowedSessionVisibilities, + hasMultipleIdentities: + this.read().context?.gateway.snapshot.hello?.policy?.hasMultipleSessionSharingIdentities, + }); + } + + showStartInTerminal(): boolean { + const { context, data } = this.read(); + return Boolean( + context && + catalog.isTarget(data) && + data?.startTerminal && + context.config.current.cliAgentsEnabled === true && + isTerminalAvailable( + context.gateway.snapshot, + context.config.current.terminalEnabled ?? false, + ), + ); + } + + private buildDraftSessionCreateParams( + options: { + message?: string; + attachments?: unknown[]; + visibility?: NewSessionVisibility; + } = {}, + ): Record { + return assembleDraftSessionCreateParams({ + agentId: this.place.agentId, + message: options.message ?? "", + model: this.place.modelControl.selected, + thinkingLevel: this.place.modelControl.thinkingLevel, + visibility: options.visibility ?? this.visibilityValue, + attachments: options.attachments, + projectId: this.place.projectId, + worktree: this.place.worktree, + baseRef: this.place.baseRef, + worktreeName: this.place.worktreeName, + cwd: this.place.folder, + workspace: this.place.workspacePath(), + execNode: this.place.execNode, + catalogId: this.read().data?.catalogId, + }); + } + + submissionAccess( + createParams: Record = this.pendingCloud.createParams ?? + this.buildDraftSessionCreateParams(), + ): SessionMethodAccess { + const gateway = this.read().context?.gateway.snapshot; + const pendingCloud = Boolean(this.pendingCloud.sessionKey); + if (!pendingCloud || this.pendingCloud.phase === "creating") { + const createAccess = readSessionMethodAccess(gateway, { + method: "sessions.create", + params: createParams, + }); + if (!createAccess.allowed || !this.cloudProfileForSubmission()) { + return createAccess; + } + } + return readSessionMethodAccess(gateway, { + method: "sessions.dispatch", + requiredScope: "operator.admin", + }); + } + + submitDisabledReason(): string | undefined { + const access = this.submissionAccess(); + return access.allowed ? undefined : access.reason; + } + + terminalStartDisabledReason(): string | undefined { + const access = this.terminalStartAccess(); + return access.allowed ? undefined : access.reason; + } + + incognitoDisabledReason(): string | undefined { + const access = readSessionMethodAccess(this.read().context?.gateway.snapshot, { + method: "sessions.create", + params: this.buildDraftSessionCreateParams({ visibility: "incognito" }), + }); + return access.allowed ? undefined : access.reason; + } + + canSubmit(kind: "session" | "terminal" = "session"): boolean { + const pendingCloud = Boolean(this.pendingCloud.sessionKey); + const cloudProfileId = this.cloudProfileForSubmission(); + const message = pendingCloud ? this.pendingCloud.message : this.messageValue.trim(); + const hasAttachments = pendingCloud + ? Boolean(this.pendingCloud.attachments?.length) + : this.attachmentDraft.attachments.length > 0; + const gateway = this.read().context?.gateway; + if ( + this.submittingValue || + this.gateway.preferenceLoading || + this.requiresModelSetup() || + this.attachmentDraft.pendingReads > 0 || + (!pendingCloud && this.submissionOutcomeUnknownValue) || + (kind === "session" && !message && !hasAttachments) || + gateway?.snapshot.phase !== "connected" || + !gateway.snapshot.client + ) { + return false; + } + const access = kind === "terminal" ? this.terminalStartAccess() : this.submissionAccess(); + if (!access.allowed || this.place.folderSubmissionBlocked()) { + return false; + } + if (this.place.modelControl.isRestoringPreference() || !this.place.worktreePreferenceReady) { + return false; + } + if (pendingCloud) { + return Boolean( + this.pendingCloud.retryAllowed && + gateway.snapshot.client.recoveryScopeReady && + cloudProfileId && + this.pendingCloud.agentId && + this.pendingCloud.gatewayUrl === gateway.connection.gatewayUrl && + this.pendingCloud.recoveryScope === gateway.snapshot.client?.recoveryScope && + this.place.isAdmin(), + ); + } + if (this.place.agents().length === 0) { + return false; + } + if (!catalog.allowsSelectedAgent(this.read().data, this.place.selectedAgent())) { + return false; + } + if (!this.place.execNodeReady()) { + return false; + } + if ( + cloudProfileId && + (!this.place.isAdmin() || + !gateway.snapshot.client.recoveryScope || + !gateway.snapshot.client.recoveryScopeReady || + !this.gateway.cloudProfilesReady || + this.gateway.cloudProfilesPending || + !this.place.worktree || + !this.gateway.cloudProfiles.some((profile) => profile.id === cloudProfileId) || + Boolean(this.cloudRuntimeUnsupportedReason())) + ) { + return false; + } + if (this.place.execNode && this.place.worktree) { + return false; + } + if (this.place.worktree && !this.place.worktreeAvailable()) { + return false; + } + if (this.place.worktree && !isWorktreeNameValid(this.place.worktreeName)) { + return false; + } + if (kind === "terminal" && !(this.place.folder.trim() || this.place.workspacePath())) { + return false; + } + return true; + } + + requiresModelSetup(): boolean { + const selectedAgent = this.place.selectedAgent(); + return requiresChatModelSetup({ + catalog: + catalog.isTarget(this.read().data) || + Boolean(this.place.cloudProfileId) || + Boolean(this.pendingCloud.sessionKey), + connected: this.gateway.connected, + agentsLoaded: this.read().context?.agents.state.agentsList !== null, + selectedAgentFound: selectedAgent !== undefined, + agentModel: selectedAgent?.model?.primary, + }); + } + + cloudDisabledReason(): string | undefined { + const runtimeReason = this.cloudRuntimeUnsupportedReason(); + if (runtimeReason) { + return runtimeReason; + } + if (this.place.repository.kind === "checking") { + return t("newSession.checkingGit"); + } + if (this.place.repository.kind === "unavailable" && !this.place.worktreeAvailable()) { + return t("newSession.gitCheckUnavailable"); + } + return this.place.worktreeAvailable() ? undefined : t("newSession.cloudRequiresWorktree"); + } + + invalidate(outcomeUnknown: SubmissionOutcomeReason | null = null) { + this.submitRequestToken += 1; + if (outcomeUnknown && this.submittingValue) { + this.submissionOutcomeUnknownValue = outcomeUnknown; + } + this.submittingValue = false; + this.callbacks.requestUpdate(); + } + + resetDraft() { + const preservePendingCloud = Boolean(this.pendingCloud.sessionKey); + this.invalidate(); + this.submissionOutcomeUnknownValue = preservePendingCloud + ? (this.submissionOutcomeUnknownValue ?? "cloud-interrupted") + : null; + this.visibilityValue = "normal"; + this.attachmentDraft.reset({ release: true }); + if (preservePendingCloud) { + if (!this.pendingCloud.restored) { + this.pendingCloud.retryAllowed = false; + } + const recovery = this.pendingCloud.capture(); + if (recovery) { + this.applyRecoveryDraft(recovery); + } + this.pendingCloud.restored = false; + } else { + this.clearPendingCloudRecovery(); + this.messageValue = ""; + } + this.errorValue = null; + this.callbacks.requestUpdate(); + } + + clearPendingCloudRecovery() { + this.pendingCloud.clear(); + this.submissionOutcomeUnknownValue = null; + this.callbacks.requestUpdate(); + } + + resetPendingCloudWithoutClearingStorage() { + this.pendingCloud.reset(); + this.submissionOutcomeUnknownValue = null; + this.callbacks.requestUpdate(); + } + + restorePendingCloudRecovery(gatewayUrl: string, recoveryScope: string) { + const recovery = this.pendingCloud.restore(gatewayUrl, recoveryScope); + if (!recovery) { + return; + } + this.applyRecoveryDraft(recovery); + this.callbacks.requestUpdate(); + } + + async submit() { + const context = this.read().context; + if (!context || !this.canSubmit()) { + return; + } + const pendingCloud = Boolean(this.pendingCloud.sessionKey); + const message = pendingCloud ? this.pendingCloud.message : this.messageValue.trim(); + const attachments = this.attachmentDraft.attachments; + const apiAttachments = pendingCloud + ? this.pendingCloud.attachments + : buildChatApiAttachments(attachments); + const submissionAgentId = pendingCloud + ? this.pendingCloud.agentId + : normalizeAgentId(this.place.agentId); + const submissionGatewayUrl = pendingCloud + ? this.pendingCloud.gatewayUrl + : context.gateway.connection.gatewayUrl; + const submissionClient = context.gateway.snapshot.client; + if (!submissionClient || !context.gateway.snapshot.hello) { + return; + } + const submissionRecoveryScope = pendingCloud + ? this.pendingCloud.recoveryScope + : submissionClient.recoveryScope; + const requestId = ++this.submitRequestToken; + const submittedAt = Date.now(); + this.submittingValue = true; + this.errorValue = null; + this.place.browser.close(); + this.callbacks.closeTransientUi(); + this.callbacks.requestUpdate(); + try { + const cloudProfileId = this.cloudProfileForSubmission(); + const draftRetired = this.visibilityValue === "draft" && !this.canStartAsDraft(); + const createParams = this.buildDraftSessionCreateParams({ + message: cloudProfileId ? "" : message, + visibility: draftRetired ? "normal" : this.visibilityValue, + attachments: cloudProfileId ? undefined : apiAttachments, + }); + const cloudCreateParams = cloudProfileId + ? pendingCloud + ? this.pendingCloud.createParams + : this.pendingCloud.stageCreate({ + agentId: submissionAgentId, + profileId: cloudProfileId, + message, + attachments: apiAttachments, + gatewayUrl: submissionGatewayUrl, + recoveryScope: submissionRecoveryScope, + createParams, + persistent: this.visibilityValue !== "incognito", + }) + : undefined; + const requestAccess = this.submissionAccess(cloudCreateParams ?? createParams); + if (!requestAccess.allowed) { + this.errorValue = requestAccess.reason; + return; + } + if (cloudProfileId && !pendingCloud && !cloudCreateParams) { + this.errorValue = t("newSession.cloudStartFailed", { + error: "cloud recovery storage is unavailable", + }); + return; + } + const submissionCloudRecovery = cloudProfileId ? this.pendingCloud.capture() : null; + if (cloudProfileId && !submissionCloudRecovery) { + this.errorValue = t("newSession.cloudStartFailed", { + error: "cloud recovery storage is unavailable", + }); + return; + } + const recoveryOwnerKey = submissionCloudRecovery?.sessionKey ?? ""; + const ownsSubmissionRecovery = () => + this.pendingCloud.owns(submissionGatewayUrl, submissionRecoveryScope, recoveryOwnerKey); + const isSubmissionLifecycleCurrent = () => + this.read().isConnected && + submissionClient.recoveryScopeReady && + requestId === this.submitRequestToken && + this.gateway.client === submissionClient && + this.gateway.gatewayUrl === submissionGatewayUrl && + this.gateway.recoveryScope === submissionRecoveryScope; + const result = + pendingCloud && this.pendingCloud.phase !== "creating" + ? { key: this.pendingCloud.sessionKey, initialRun: { status: "idle" as const } } + : await context.sessions.createResult(cloudCreateParams ?? createParams, { + reconciliation: "background", + }); + if (requestId !== this.submitRequestToken && !cloudProfileId) { + return; + } + if (!result) { + if (requestId !== this.submitRequestToken) { + return; + } + this.errorValue = context.sessions.state.error ?? t("newSession.createFailed"); + return; + } + if (cloudProfileId && submissionCloudRecovery) { + if ( + submissionCloudRecovery.phase === "creating" && + (!isSubmissionLifecycleCurrent() || !ownsSubmissionRecovery()) + ) { + const cleanupError = await deleteCloudDraftSession( + submissionClient, + result.key, + submissionAgentId, + ); + if (cleanupError) { + this.pendingCloud.promoteToDispatching(result.key); + this.pendingCloud.retryAllowed = true; + this.errorValue = t("newSession.cloudStartFailed", { error: cleanupError }); + this.callbacks.requestUpdate(); + } else { + this.clearPendingCloudRecovery(); + } + return; + } + if ( + submissionCloudRecovery.phase === "creating" && + isSubmissionLifecycleCurrent() && + ownsSubmissionRecovery() + ) { + if (!this.pendingCloud.promoteToDispatching(result.key)) { + this.errorValue = t("newSession.cloudStartFailed", { + error: "cloud recovery storage is unavailable", + }); + return; + } + } + const recovery = this.pendingCloud.capture(); + if (!recovery || recovery.phase === "creating") { + this.errorValue = t("newSession.cloudStartFailed", { + error: "cloud recovery storage is unavailable", + }); + return; + } + if (requestId !== this.submitRequestToken) { + return; + } + context.cloudStartup.start({ + recovery, + persistRecovery: this.pendingCloud.persistent, + recovering: pendingCloud, + createdAt: submittedAt, + }); + if ( + requestId !== this.submitRequestToken || + !isSubmissionLifecycleCurrent() || + !this.pendingCloud.owns( + submissionGatewayUrl, + submissionRecoveryScope, + recovery.sessionKey, + ) + ) { + return; + } + this.pendingCloud.reset(); + this.attachmentDraft.clearAfterSubmit(true); + selectApplicationSession({ + selection: context.agentSelection, + gateway: context.gateway, + sessionKey: result.key, + agentId: submissionAgentId, + }); + context.navigate( + "chat", + sessionNavigationTarget({ + context, + face: "chat", + sessionKey: result.key, + agentId: this.place.agentId, + }).options, + ); + return; + } + if (requestId !== this.submitRequestToken) { + return; + } + const handedOffAttachments = + result.initialRun.status === "rejected" && + retainRejectedInitialTurn({ + agentId: this.place.agentId, + attachments, + context, + error: result.initialRun.error, + message, + sessionKey: result.key, + }); + if (result.initialRun.status === "started") { + prepareInitialUserMessageHandoff( + context.initialUserMessage, + result.key, + { text: message, attachments, createdAt: submittedAt }, + submissionClient, + { runId: result.initialRun.runId, messageSeq: result.initialRun.messageSeq }, + ); + } + this.attachmentDraft.clearAfterSubmit(!handedOffAttachments); + if (requestId !== this.submitRequestToken) { + return; + } + selectApplicationSession({ + selection: context.agentSelection, + gateway: context.gateway, + sessionKey: result.key, + agentId: submissionAgentId, + }); + context.navigate( + "chat", + sessionNavigationTarget({ + context, + face: "chat", + sessionKey: result.key, + agentId: this.place.agentId, + }).options, + ); + } finally { + if (requestId === this.submitRequestToken) { + this.submittingValue = false; + this.callbacks.requestUpdate(); + } + } + } + + async startInTerminal() { + const { context, data } = this.read(); + const client = context?.gateway.snapshot.client; + const catalogId = data?.catalogId.trim() ?? ""; + const agentId = normalizeAgentId(this.place.agentId); + if (!context || !client || !catalogId || !agentId || !this.canSubmit("terminal")) { + return; + } + const requestId = ++this.submitRequestToken; + const initialMessage = this.messageValue.trim(); + this.submittingValue = true; + this.errorValue = null; + this.place.browser.close(); + this.callbacks.closeTransientUi(); + this.callbacks.requestUpdate(); + try { + let cwd = this.place.folder.trim() || this.place.workspacePath(); + if (this.place.worktree) { + const created = await createManagedWorktree(client, { + repoRoot: cwd, + name: this.place.worktreeName, + baseRef: this.place.baseRef, + }); + if (requestId !== this.submitRequestToken || this.gateway.client !== client) { + return; + } + cwd = created.path; + } + const result = await client.request( + "sessions.catalog.startTerminal", + { + catalogId, + ...(this.place.execNode ? { hostId: `node:${this.place.execNode}` } : {}), + agentId, + cwd, + ...(initialMessage ? { initialMessage } : {}), + }, + ); + if (requestId !== this.submitRequestToken || this.gateway.client !== client) { + return; + } + this.messageValue = ""; + openTerminalSessionInTerminal(result.sessionId); + } catch (error) { + if (requestId === this.submitRequestToken && this.gateway.client === client) { + this.errorValue = error instanceof Error ? error.message : String(error); + } + } finally { + if (requestId === this.submitRequestToken) { + this.submittingValue = false; + this.callbacks.requestUpdate(); + } + } + } + + disconnect() { + this.attachmentDraft.reset({ release: true }); + this.composerTextarea.disconnect(); + } + + private terminalStartAccess(): SessionMethodAccess { + const gateway = this.read().context?.gateway.snapshot; + const terminalAccess = readSessionMethodAccess(gateway, { + method: "sessions.catalog.startTerminal", + requiredScope: "operator.admin", + }); + if (!terminalAccess.allowed || !this.place.worktree) { + return terminalAccess; + } + return readSessionMethodAccess(gateway, { + method: "worktrees.create", + requiredScope: "operator.admin", + }); + } + + private cloudProfileForSubmission(): string { + return this.pendingCloud.sessionKey ? this.pendingCloud.profileId : this.place.cloudProfileId; + } + + private cloudRuntimeUnsupportedReason(): string | undefined { + const runtime = this.place.modelControl.resolveAgentRuntimeId({ + agent: this.place.selectedAgent(), + context: this.read().context, + }); + return runtime && runtime !== "openclaw" + ? t("newSession.cloudRequiresOpenClawRuntime", { runtime }) + : undefined; + } + + private applyRecoveryDraft(recovery: CloudSessionRecovery) { + this.place.applyPendingCloud({ + agentId: recovery.agentId, + profileId: recovery.profileId, + cwd: recovery.createParams?.cwd, + }); + this.visibilityValue = recovery.createParams?.incognito === true ? "incognito" : "normal"; + this.messageValue = recovery.message; + this.attachmentDraft.replace(restoreChatApiAttachments(recovery.attachments)); + } +} diff --git a/ui/src/pages/new-session/new-session-page.test.ts b/ui/src/pages/new-session/new-session-page.test.ts index 6cf9c48505a6..b0531119ca13 100644 --- a/ui/src/pages/new-session/new-session-page.test.ts +++ b/ui/src/pages/new-session/new-session-page.test.ts @@ -1,44 +1,10 @@ -import { render, type TemplateResult } from "lit"; -import { afterEach, describe, expect, it, vi } from "vitest"; -import type { ApplicationContext } from "../../app/context.ts"; -import type { ChatAttachment } from "../../lib/chat/chat-types.ts"; -import type { CloudSessionRecovery } from "../../lib/sessions/cloud-recovery.ts"; +import { afterEach, describe, expect, it } from "vitest"; import type { NewSessionRouteData } from "./location.ts"; import "./new-session-page.ts"; -type TestNewSessionPage = { +type NewSessionElement = HTMLElement & { data: NewSessionRouteData | undefined; - folder: string; - message: string; - openedFor: string | null; - visibility: "normal" | "draft" | "incognito"; - worktree: boolean; - agentId: string; - cloudProfileId: string; - context: ApplicationContext; - error: string | null; - submitting: boolean; - gatewayClient: ApplicationContext["gateway"]["snapshot"]["client"]; - gatewayConnected: boolean; - gatewayRecoveryScope: string; - gatewayUrl: string; - projectRecents: unknown; - projectsTask: { - run( - args: readonly [ApplicationContext["gateway"]["snapshot"]["client"], boolean, number], - ): Promise; - }; - pendingCloud: { capture(): CloudSessionRecovery | null }; - attachmentDraft: { - attachments: ChatAttachment[]; - replace(attachments: ChatAttachment[]): void; - }; - canSubmit(): boolean; - submissionAccess(): { allowed: true }; - submit(): Promise; - setMessageFromUser(message: string): void; - renderPlaceSelect(): TemplateResult; - updated(): void; + updateComplete: Promise; }; function routeData(agentId: string, catalogId = ""): NewSessionRouteData { @@ -52,6 +18,34 @@ function routeData(agentId: string, catalogId = ""): NewSessionRouteData { }; } +async function mount(data: NewSessionRouteData): Promise { + const page = document.createElement("openclaw-new-session-page") as NewSessionElement; + page.data = data; + document.body.append(page); + await settle(page); + return page; +} + +async function settle(page: NewSessionElement) { + await page.updateComplete; + await page.updateComplete; +} + +async function enterMessage(page: NewSessionElement, value: string) { + const textarea = page.querySelector(".new-session-page__message"); + expect(textarea).not.toBeNull(); + if (!textarea) { + return; + } + textarea.value = value; + textarea.dispatchEvent(new InputEvent("input", { bubbles: true, composed: true })); + await settle(page); +} + +function message(page: NewSessionElement): string { + return page.querySelector(".new-session-page__message")?.value ?? ""; +} + afterEach(() => { document.querySelectorAll("openclaw-new-session-page").forEach((element) => element.remove()); sessionStorage.clear(); @@ -59,203 +53,44 @@ afterEach(() => { }); describe("new session draft route ownership", () => { - it("clears all source draft state when destination data is still pending", () => { - const page = document.createElement( - "openclaw-new-session-page", - ) as unknown as TestNewSessionPage; - page.data = routeData("research"); - page.updated(); + it("clears source draft state when destination data is still pending", async () => { + const page = await mount(routeData("research")); window.history.replaceState({}, "", "/new?agent=research"); - page.setMessageFromUser("source draft"); - page.folder = "/workspace/source"; - page.visibility = "incognito"; - page.worktree = true; + await enterMessage(page, "source draft"); window.history.replaceState({}, "", "/new?agent=research&catalog=claude"); page.data = undefined; - page.updated(); + await settle(page); - expect(page.message).toBe(""); - expect(page.folder).toBe(""); - expect(page.visibility).toBe("normal"); - expect(page.worktree).toBe(false); - expect(page.openedFor).toBe(JSON.stringify(["research", "claude"])); + expect(message(page)).toBe(""); }); - it("keeps destination input through pending data, settlement, and agent resolution", () => { - const page = document.createElement( - "openclaw-new-session-page", - ) as unknown as TestNewSessionPage; - page.data = routeData("research"); - page.updated(); + it("keeps destination input through pending data, settlement, and agent resolution", async () => { + const page = await mount(routeData("research")); window.history.replaceState({}, "", "/new?agent=research&catalog=claude"); page.data = undefined; - page.updated(); - page.setMessageFromUser("keep this fast draft"); + await settle(page); + await enterMessage(page, "keep this fast draft"); - page.data = { - ...routeData("", "claude"), - requestedAgentId: "research", - }; - page.updated(); - expect(page.message).toBe("keep this fast draft"); + page.data = { ...routeData("", "claude"), requestedAgentId: "research" }; + await settle(page); + expect(message(page)).toBe("keep this fast draft"); page.data = routeData("research", "claude"); - page.updated(); - - expect(page.message).toBe("keep this fast draft"); + await settle(page); + expect(message(page)).toBe("keep this fast draft"); }); - it("clears a draft when a different route settles without destination-owned input", () => { - const page = document.createElement( - "openclaw-new-session-page", - ) as unknown as TestNewSessionPage; - page.data = routeData("research", "claude"); - page.updated(); + it("clears a draft when a different route settles without destination-owned input", async () => { + const page = await mount(routeData("research", "claude")); window.history.replaceState({}, "", "/new?agent=research&catalog=claude"); - page.setMessageFromUser("route-owned draft"); + await enterMessage(page, "route-owned draft"); window.history.replaceState({}, "", "/new?agent=main&catalog=codex"); page.data = undefined; - page.updated(); + await settle(page); - expect(page.message).toBe(""); - }); - - it("hands cloud startup to the application owner and navigates immediately", async () => { - window.history.replaceState({}, "", "/new"); - const page = document.createElement( - "openclaw-new-session-page", - ) as unknown as TestNewSessionPage; - Object.defineProperty(page, "isConnected", { configurable: true, value: true }); - const client = { recoveryScope: "principal-a", recoveryScopeReady: true }; - const createResult = vi.fn(async (params: Record) => ({ - key: String(params.key), - initialRun: { status: "idle" as const }, - })); - const start = vi.fn( - (_input: Parameters[0]) => - new Promise(() => { - // The application owner keeps loading after this route commits. - }), - ); - const navigate = vi.fn(); - const setSessionKey = vi.fn(); - const selectAgent = vi.fn(); - page.context = { - basePath: "", - gateway: { - connection: { gatewayUrl: "ws://gateway.example" }, - snapshot: { - phase: "connected", - client, - hello: { auth: { role: "operator", scopes: ["operator.admin"] } }, - }, - setSessionKey, - }, - agents: { state: { agentsList: null } }, - agentSelection: { state: { selectedId: "cloud" }, set: selectAgent }, - sessions: { state: { result: null }, createResult }, - cloudStartup: { start }, - navigate, - } as unknown as ApplicationContext; - page.agentId = "cloud"; - page.cloudProfileId = "aws"; - page.message = "keep this cloud task"; - page.visibility = "normal"; - page.worktree = true; - page.gatewayClient = client as ApplicationContext["gateway"]["snapshot"]["client"]; - page.gatewayConnected = true; - page.gatewayRecoveryScope = client.recoveryScope; - page.gatewayUrl = "ws://gateway.example"; - page.canSubmit = () => true; - page.submissionAccess = () => ({ allowed: true }); - page.attachmentDraft.replace([ - { - id: "attachment-1", - dataUrl: "data:text/plain;base64,SGk=", - mimeType: "text/plain", - fileName: "note.txt", - }, - ]); - - await page.submit(); - expect(start).toHaveBeenCalledOnce(); - expect(start.mock.calls[0]?.[0].recovery).toMatchObject({ - message: "keep this cloud task", - attachments: [{ fileName: "note.txt", content: "SGk=" }], - phase: "dispatching", - }); - expect(page.pendingCloud.capture()).toBeNull(); - expect(page.attachmentDraft.attachments).toHaveLength(0); - expect(page.submitting).toBe(false); - expect(createResult).toHaveBeenCalledOnce(); - expect(setSessionKey).toHaveBeenCalledWith(start.mock.calls[0]?.[0].recovery.sessionKey); - expect(selectAgent).toHaveBeenCalledWith("cloud"); - expect(navigate).toHaveBeenCalledOnce(); - }); -}); - -describe("new session project recents", () => { - const recentSession = { execCwd: "/workspace/recent" }; - - function createRecentsPage(request: (method: string) => Promise) { - const page = document.createElement( - "openclaw-new-session-page", - ) as unknown as TestNewSessionPage; - const client = { request } as unknown as ApplicationContext["gateway"]["snapshot"]["client"]; - page.agentId = "main"; - page.gatewayClient = client; - page.gatewayConnected = true; - page.gatewayUrl = "ws://gateway.example"; - page.context = { - gateway: { - connection: { gatewayUrl: page.gatewayUrl }, - snapshot: { - phase: "connected", - client, - selfUser: { id: "profile-a" }, - hello: { auth: { role: "operator", scopes: ["operator.read"] } }, - }, - }, - agents: { - state: { - agentsList: { - defaultId: "main", - mainKey: "main", - agents: [{ id: "main", workspace: "/workspace" }], - }, - }, - }, - sessions: { state: { result: { sessions: [recentSession] } } }, - config: { current: {} }, - } as unknown as ApplicationContext; - return { client, page }; - } - - async function expectRosterRecent(page: TestNewSessionPage) { - expect(page.projectRecents).toBeUndefined(); - const host = document.createElement("div"); - render(page.renderPlaceSelect(), host); - expect(host.querySelector('[data-value="recent::/workspace/recent"]')).not.toBeNull(); - } - - it("falls back to roster recents when projects.list omits server recents", async () => { - const { client, page } = createRecentsPage(async () => ({ projects: [] })); - - await page.projectsTask.run([client, true, 1]); - - await expectRosterRecent(page); - }); - - it("falls back to roster recents when projects.list fails", async () => { - const { client, page } = createRecentsPage(async () => { - throw new Error("projects unavailable"); - }); - - await page.projectsTask.run([client, true, 1]); - - await expectRosterRecent(page); + expect(message(page)).toBe(""); }); }); diff --git a/ui/src/pages/new-session/new-session-page.ts b/ui/src/pages/new-session/new-session-page.ts index e31708e723fb..5c73aa02e6f4 100644 --- a/ui/src/pages/new-session/new-session-page.ts +++ b/ui/src/pages/new-session/new-session-page.ts @@ -1,102 +1,44 @@ import { consume } from "@lit/context"; -import { initialState, Task, TaskStatus } from "@lit/task"; -import { html, nothing } from "lit"; -import { property, state } from "lit/decorators.js"; -import type { - FsListDirResult, - ProjectRecord, - ProjectRecent, - ProjectsAddResult, - ProjectsListResult, - ProjectsRegisterResult, - ProjectsSearchRemoteResult, - SessionsCatalogStartTerminalResult, - UsersPrefsGetResult, - UsersPrefsSetResult, - WorktreesBranchesResult, -} from "../../../../packages/gateway-protocol/src/index.js"; +import { html, nothing, type ReactiveController, type ReactiveControllerHost } from "lit"; +import { property } from "lit/decorators.js"; import { selectApplicationSession } from "../../app/agent-selection.ts"; import { applicationContext, type ApplicationContext } from "../../app/context.ts"; import { beginNativeWindowDragFromTopInset } from "../../app/native-window-drag.ts"; -import { hasOperatorAdminAccess, hasOperatorWriteAccess } from "../../app/operator-access.ts"; import { loadSettings } from "../../app/settings.ts"; import "../../components/tooltip.ts"; import "../../components/web-awesome-popover.ts"; import { t } from "../../i18n/index.ts"; -import { listSelectableAgents } from "../../lib/agents/display.ts"; -import { canCallGatewayMethod, isGatewayMethodAdvertised } from "../../lib/gateway-methods.ts"; -import { - readSessionMethodAccess, - type SessionMethodAccess, -} from "../../lib/session-method-access.ts"; -import { openTerminalSessionInTerminal } from "../../lib/sessions/catalog-terminal.ts"; -import { deleteCloudDraftSession } from "../../lib/sessions/cloud-startup.ts"; +import { canCallGatewayMethod } from "../../lib/gateway-methods.ts"; import { sessionNavigationTarget } from "../../lib/sessions/route-navigation.ts"; -import { buildAgentMainSessionKey, normalizeAgentId } from "../../lib/sessions/session-key.ts"; -import { normalizeOptionalString } from "../../lib/string-coerce.ts"; -import { isTerminalAvailable } from "../../lib/terminal-availability.ts"; -import { createManagedWorktree } from "../../lib/worktrees/create-worktree.ts"; +import { buildAgentMainSessionKey } from "../../lib/sessions/session-key.ts"; import { OpenClawLightDomElement } from "../../lit/openclaw-element.ts"; +import { SubscriptionsController } from "../../lit/subscriptions-controller.ts"; import "../../styles/chat.css"; import "../../styles/new-session.css"; -import { SubscriptionsController } from "../../lit/subscriptions-controller.ts"; -import { buildChatApiAttachments, restoreChatApiAttachments } from "../chat/attachment-api.ts"; -import { requiresChatModelSetup } from "../chat/chat-model-setup.ts"; import { clearChatModelSearchOnEscape } from "../chat/components/chat-model-picker.ts"; import { renderWelcomeState } from "../chat/components/chat-welcome.ts"; -import { prepareInitialUserMessageHandoff } from "../chat/initial-turn-handoff.ts"; -import { NewSessionAttachmentDraft } from "./attachment-draft.ts"; import * as catalog from "./catalog-target.ts"; -import { - CLOUD_PROFILE_RETRY_DELAYS_MS, - discoverCloudProfiles, - selectProfiles, -} from "./cloud-profile-discovery.ts"; -import { - PendingCloudRecoveryState, - resolveSubmissionOutcomeReason, - resolveScope, - type SubmissionOutcomeReason, -} from "./cloud-recovery-state.ts"; -import { - NewSessionComposerTextareaController, - renderDraftError, - renderNewSessionDraftComposer, -} from "./composer.ts"; -import { - buildDraftSessionCreateParams, - canStartSessionAsDraft, - isWorktreeNameValid, - type NewSessionVisibility, -} from "./create-params.ts"; -import { - type BrowserTarget, - type DraftCloudProfile, - type DraftNode, - type DraftRepositoryState, - readDraftNodes, -} from "./discovery.ts"; -import { isMissingRestoredFolderError } from "./folder-validation.ts"; -import { discoverGatewayName } from "./gateway-name-discovery.ts"; -import { newSessionSearch, type NewSessionRouteData } from "./location.ts"; -import { NewSessionModelControl } from "./model-control.ts"; -import { isAbsolutePath, isKnownWorkspacePath } from "./path.ts"; -import { projectCloneInput, renderPlaceSelect } from "./place-picker.ts"; -import { - decodeIdentityPreferences, - encodeIdentityPreferences, - loadBrowserPreferences, - loadNewSessionPreference, - patchNewSessionPreference, - PREFS_MIGRATION_KEY, - replaceBrowserPreference, - type NewSessionPreference, -} from "./preferences.ts"; -import { retainRejectedInitialTurn } from "./rejected-initial-turn.ts"; +import type { SubmissionOutcomeReason } from "./cloud-recovery-state.ts"; +import { renderDraftError, renderNewSessionDraftComposer } from "./composer.ts"; +import { isWorktreeNameValid } from "./create-params.ts"; +import { DraftGatewayState } from "./draft-gateway-state.ts"; +import { DraftPlaceBrowser } from "./draft-place-browser.ts"; +import { DraftPlaceState } from "./draft-place-state.ts"; +import { DraftSubmissionFlow } from "./draft-submission-flow.ts"; +import type { NewSessionRouteData } from "./location.ts"; +import { renderPlaceSelect } from "./place-picker.ts"; import { renderAgentSelect } from "./target-controls.ts"; -const CATALOG_RETRY_DELAYS_MS = [0, 1_000, 3_000] as const; -const PROJECT_SEARCH_DEBOUNCE_MS = 300; +function controllerHost(element: OpenClawLightDomElement): ReactiveControllerHost { + return { + addController: (controller: ReactiveController) => element.addController(controller), + removeController: (controller: ReactiveController) => element.removeController(controller), + requestUpdate: () => element.requestUpdate(), + get updateComplete() { + return element.updateComplete; + }, + }; +} class NewSessionPage extends OpenClawLightDomElement { @property({ attribute: false }) data: NewSessionRouteData | undefined; @@ -104,506 +46,119 @@ class NewSessionPage extends OpenClawLightDomElement { @consume({ context: applicationContext, subscribe: true }) private context?: ApplicationContext; - @state() private agentId = ""; - @state() private folder = ""; - @state() private projects: ProjectRecord[] = []; - @state() private projectRecents: ProjectRecent[] | undefined; - @state() private projectId = ""; - @state() private projectQuery = ""; - @state() private debouncedProjectQuery = ""; - @state() private projectCloneBusy = false; - @state() private projectCloneError: string | null = null; - @state() private worktree = false; - @state() private visibility: NewSessionVisibility = "normal"; - @state() private worktreeName = ""; - @state() private baseRef = ""; - @state() private repository: DraftRepositoryState = { kind: "idle" }; - @state() private nodes: DraftNode[] = []; - @state() private gatewayName = ""; - @state() private execNode = ""; - @state() private cloudProfiles: DraftCloudProfile[] = []; - @state() private cloudProfilesReady = false; - @state() private cloudProfileId = ""; - @state() private message = ""; - @state() private submitting = false; - @state() private submissionOutcomeUnknown: SubmissionOutcomeReason | null = null; - @state() private error: string | null = null; - @state() private catalogRetrying = false; - @state() private browserLoading = false; - @state() private browserError: string | null = null; - @state() private browserListing: FsListDirResult | null = null; - @state() private browserTarget: BrowserTarget | null = null; - @state() private browserProjectPath: string | null = null; - @state() private browserRegistering = false; - @state() private placePopoverOpen = false; - @state() private placePopoverHiding = false; - // Live head input; absolute paths stay applicable even without fs.listDir. - @state() private browserPathDraft = ""; - @state() private restoredFolderValidation: "none" | "checking" | "failed" = "none"; - @state() private gatewayApprovedWorkspaceRoots: string[] = []; - private openedFor: string | null = null; private openedAgentId = ""; private messageOwnerKey = ""; - private agentsHydrated = false; - private nodesHydrated = false; - // Discovery retry provenance separates user choices from Gateway-derived defaults. - private agentSelectedByUser = false; - private folderSelectedByUser = false; - private folderGatewayApproved = false; - private preferredWorktreeRestore = false; - private worktreeSelectedByUser = false; - private submitRequestToken = 0; - private nodesRequestToken = 0; - private readonly pendingCloud = new PendingCloudRecoveryState(); - private branchesRequestToken = 0; - private baseRefEditGeneration = 0; - private browserRequestToken = 0; - private projectCloneRequestToken = 0; - private projectSearchTimer: ReturnType | undefined; - private restoredFolderValidationToken = 0; - private readonly attachmentDraft = new NewSessionAttachmentDraft(() => this.requestUpdate()); - private readonly composerTextarea = new NewSessionComposerTextareaController(); - private readonly modelControl = new NewSessionModelControl( - () => this.requestUpdate(), - (selection) => this.persistPreference(selection), - (catalogId) => - this.context?.navigate("new-session", { - search: newSessionSearch(this.agentId, { catalogId }), + private readonly gateway: DraftGatewayState; + private readonly browser: DraftPlaceBrowser; + private readonly place: DraftPlaceState; + private readonly submission: DraftSubmissionFlow; + private readonly subscriptions: SubscriptionsController; + + constructor() { + super(); + const host = controllerHost(this); + this.gateway = new DraftGatewayState( + host, + () => ({ + context: this.context, + data: this.data, + isConnected: this.isConnected, + isAdmin: this.place?.isAdmin() ?? false, + canStartAsDraft: this.submission?.canStartAsDraft() ?? false, + visibility: this.submission?.visibility ?? "normal", + cloudProfileId: this.place?.cloudProfileId ?? "", + pendingCloud: this.submission?.pendingCloud ?? { + sessionKey: "", + gatewayUrl: "", + recoveryScope: "", + }, + agentsHydrated: this.place?.agentsHydrated ?? false, }), - ); - private gatewaySource: ApplicationContext["gateway"] | null = null; - private gatewayClient: ApplicationContext["gateway"]["snapshot"]["client"] = null; - private gatewayUrl = ""; - private gatewayRecoveryScope = ""; - private gatewayRecoveryScopeReady = false; - private gatewayConnected = false; - private gatewayConnectionEpoch = 0; - private catalogRetryScope = ""; - private catalogRetryAttempt = 0; - private catalogRetryTimer: ReturnType | undefined; - private cloudProfileRetryAttempt = 0; - private cloudProfileRetryTimer: ReturnType | undefined; - private preferenceScope = ""; - private preferenceMode: "local" | "loading" | "remote" = "local"; - private identityPreferences: Record = {}; - private preferenceLoad: Promise = Promise.resolve(); - private preferenceWrite: Promise = Promise.resolve(); - - // Re-render when agents/sessions hydrate so the hero identity and the - // recent-chats list appear without a route change. - private readonly subscriptions = new SubscriptionsController(this) - .watch( - () => this.context?.gateway, - (gateway, notify) => gateway.subscribe(notify), - (gateway) => this.synchronizeGateway(gateway), - ) - .watch( - () => this.context?.agents, - (agents, notify) => agents.subscribe(notify), - ) - .watch( - () => this.context?.sessions, - (sessions, notify) => sessions.subscribe(notify), - ) - .watch( - () => this.context?.config, - (config, notify) => config.subscribe(() => notify()), + { + requestUpdate: () => this.requestUpdate(), + updateComplete: () => this.updateComplete, + onInvalidate: (resetHostSelection, outcome) => + this.invalidateGatewayDiscovery(resetHostSelection, outcome), + onVisibilityRetired: () => this.submission.setVisibility("normal"), + onCloudProfileCleared: () => this.place.clearCloudProfile(), + onCloudState: (error) => this.submission.setError(error), + onPendingCloudReset: () => this.submission.resetPendingCloudWithoutClearingStorage(), + onRecoveryReady: (gatewayUrl, recoveryScope) => + this.submission.restorePendingCloudRecovery(gatewayUrl, recoveryScope), + onAdoptAgentDefaults: () => + this.place.adoptAgentDefaults({ + preserveSelectedAgent: true, + preserveSelectedFolder: true, + }), + }, ); - - private readonly gatewayNameTask = new Task(this, { - args: () => - [ - this.isConnected && this.gatewayConnected ? this.gatewayClient : null, - this.context - ? isGatewayMethodAdvertised(this.context.gateway.snapshot, "system.info") === true - : false, - this.gatewayConnectionEpoch, - ] as const, - task: ([client, advertised, _connectionEpoch], { signal }) => - discoverGatewayName(client, advertised, signal), - onComplete: (name) => { - this.gatewayName = name; - }, - }); - - private readonly projectsTask = new Task(this, { - args: () => - [ - this.isConnected && this.gatewayConnected ? this.gatewayClient : null, - this.context - ? isGatewayMethodAdvertised(this.context.gateway.snapshot, "projects.list") === true - : false, - this.gatewayConnectionEpoch, - ] as const, - task: async ([client, advertised]) => { - if (!client || !advertised) { - return { projects: [] } as ProjectsListResult; - } - return await client.request("projects.list", {}); - }, - onComplete: (result) => { - const projects = result.projects ?? []; - this.projects = projects; - this.projectRecents = result.recents; - if (this.projectId && !projects.some((project) => project.id === this.projectId)) { - this.projectId = ""; - this.maybeLoadBranches(); - } - }, - onError: () => { - this.projects = []; - this.projectRecents = undefined; - this.projectId = ""; - }, - }); - - private readonly projectSearchTask = new Task(this, { - args: () => - [ - this.isConnected && this.gatewayConnected ? this.gatewayClient : null, - this.context - ? canCallGatewayMethod( - this.context.gateway.snapshot, - "projects.searchRemote", - "operator.read", - ) - : false, - this.debouncedProjectQuery, - this.gatewayConnectionEpoch, - ] as const, - task: ([client, advertised, query, _connectionEpoch], { signal }) => { - if (!client || !advertised || query.length < 2 || projectCloneInput(query)) { - return initialState; - } - return client.request( - "projects.searchRemote", - { query }, - { signal }, - ); - }, - }); - - private readonly cloudProfileTask = new Task(this, { - args: () => - [ - this.isConnected && this.gatewayConnected ? this.gatewayClient : null, - this.gatewayConnectionEpoch, - this.isAdmin(), - this.gatewayRecoveryScope, - ] as const, - task: ([client, _connectionEpoch, admin]) => - client ? discoverCloudProfiles(client, admin) : initialState, - onComplete: (profiles) => { - this.resetCloudProfileRetry(); - this.applyCloudProfiles(profiles); - this.cloudProfilesReady = true; - }, - onError: () => { - this.cloudProfiles = []; - this.cloudProfilesReady = false; - this.scheduleCloudProfileRetry(); - }, - }); - - private applyCloudProfiles(profiles: DraftCloudProfile[]) { - const recovery = selectProfiles(profiles, this.gatewayClient, this.gatewayRecoveryScope); - this.cloudProfiles = recovery.profiles; - const pendingCloud = Boolean(this.pendingCloud.sessionKey); - if ((!this.gatewayConnected || !this.isAdmin()) && !pendingCloud) { - this.cloudProfileId = ""; - this.closeBrowser(); - } - const selectionUnavailable = - !pendingCloud && - Boolean(this.cloudProfileId) && - !profiles.some((profile) => profile.id === this.cloudProfileId); - if (selectionUnavailable) { - this.error = t("newSession.catalogUnavailable"); - } else if (recovery.unsupported) { - this.error = t("newSession.cloudRecoveryUnavailable"); - } else if (this.error === t("newSession.cloudRecoveryUnavailable")) { - this.error = null; - } - } - - private resetCloudProfileRetry() { - globalThis.clearTimeout(this.cloudProfileRetryTimer); - this.cloudProfileRetryTimer = undefined; - this.cloudProfileRetryAttempt = 0; - } - - private scheduleCloudProfileRetry() { - if (this.cloudProfileRetryTimer || !this.gatewayConnected || !this.gatewayClient) { - return; - } - if (this.cloudProfileRetryAttempt >= CLOUD_PROFILE_RETRY_DELAYS_MS.length) { - this.applyCloudProfiles([]); - this.cloudProfilesReady = true; - return; - } - const delayMs = CLOUD_PROFILE_RETRY_DELAYS_MS[this.cloudProfileRetryAttempt]; - this.cloudProfileRetryAttempt += 1; - this.cloudProfileRetryTimer = globalThis.setTimeout(() => { - this.cloudProfileRetryTimer = undefined; - if (this.gatewayConnected) { - void this.cloudProfileTask.run(); - } - }, delayMs); - } - - private synchronizeGateway(gateway: ApplicationContext["gateway"]) { - const snapshot = gateway.snapshot; - const connected = snapshot.phase === "connected"; - const firstBind = this.gatewaySource === null; - const gatewayUrlChanged = !firstBind && this.gatewayUrl !== gateway.connection.gatewayUrl; - const identityChanged = - !firstBind && (this.gatewaySource !== gateway || this.gatewayClient !== snapshot.client); - const connectionChanged = !firstBind && this.gatewayConnected !== connected; - const becameConnected = connected && (identityChanged || !this.gatewayConnected); - const recoveryScopeBecameReady = - connected && snapshot.client?.recoveryScopeReady === true && !this.gatewayRecoveryScopeReady; - const recoveryScope = resolveScope( - { client: snapshot.client, connected }, - this.gatewayRecoveryScope, - firstBind, + this.browser = new DraftPlaceBrowser( + host, + this.gateway, + () => ({ + context: this.context, + projectId: this.place?.projectId ?? "", + nodes: this.place?.nodes ?? [], + folder: this.place?.folder ?? "", + execNode: this.place?.execNode ?? "", + isAdmin: this.place?.isAdmin() ?? false, + }), + { + requestUpdate: () => this.requestUpdate(), + onProjectMissing: () => this.place.clearProjectSelection(), + onSelectProject: (projectId) => this.place.selectProjectId(projectId), + onApplyFolder: (folder, execNode, gatewayApproved) => + this.place.applyFolder(folder, execNode, gatewayApproved), + onApprovedListing: (listing) => this.place.recordGatewayApprovedListing(listing), + querySelector: (selector) => this.querySelector(selector), + activeElement: () => this.ownerDocument.activeElement, + body: () => this.ownerDocument.body, + }, ); - this.gatewaySource = gateway; - this.gatewayClient = snapshot.client; - this.gatewayUrl = gateway.connection.gatewayUrl; - this.gatewayRecoveryScope = recoveryScope.next; - this.gatewayRecoveryScopeReady = snapshot.client?.recoveryScopeReady === true; - this.gatewayConnected = connected; - if (this.visibility === "draft" && !this.canStartAsDraft()) { - this.visibility = "normal"; - } - if (gatewayUrlChanged || identityChanged || connectionChanged || recoveryScope.changed) { - const gatewayIdentityChanged = gatewayUrlChanged || recoveryScope.changed; - this.invalidateGatewayDiscovery( - gatewayIdentityChanged, - resolveSubmissionOutcomeReason({ - gatewayIdentityChanged, - cloudDraftOwned: Boolean(this.pendingCloud.sessionKey), - }), + this.place = new DraftPlaceState( + this.gateway, + this.browser, + () => ({ + context: this.context, + data: this.data, + submitting: this.submission?.submitting ?? false, + pendingCloudSessionKey: this.submission?.pendingCloud.sessionKey ?? "", + }), + { + requestUpdate: () => this.requestUpdate(), + onError: (error) => + error === null ? this.submission.clearError() : this.submission.setError(error), + onClearError: (error) => this.submission.clearErrorIf(error), + }, + ); + this.submission = new DraftSubmissionFlow( + this.gateway, + this.place, + () => ({ context: this.context, data: this.data, isConnected: this.isConnected }), + { + requestUpdate: () => this.requestUpdate(), + closeTransientUi: () => this.closeOpenDropdowns(), + }, + ); + this.subscriptions = new SubscriptionsController(this) + .watch( + () => this.context?.gateway, + (gateway, notify) => gateway.subscribe(notify), + (gateway) => this.gateway.synchronize(gateway), + ) + .watch( + () => this.context?.agents, + (agents, notify) => agents.subscribe(notify), + ) + .watch( + () => this.context?.sessions, + (sessions, notify) => sessions.subscribe(notify), + ) + .watch( + () => this.context?.config, + (config, notify) => config.subscribe(() => notify()), ); - } - if ( - firstBind || - gatewayUrlChanged || - recoveryScope.changed || - recoveryScopeBecameReady || - becameConnected - ) { - if ( - this.pendingCloud.gatewayUrl && - (this.pendingCloud.gatewayUrl !== this.gatewayUrl || - this.pendingCloud.recoveryScope !== this.gatewayRecoveryScope) - ) { - this.pendingCloud.reset(); - this.submissionOutcomeUnknown = null; - } - if (connected && snapshot.client?.recoveryScopeReady) { - this.restorePendingCloudRecovery(this.gatewayUrl, this.gatewayRecoveryScope); - } - } - if (becameConnected || recoveryScope.changed) { - if (becameConnected) { - this.gatewayConnectionEpoch += 1; - this.retryPendingCatalogTarget(); - } - } - this.synchronizeIdentityPreferences(snapshot.selfUser?.id); - } - - private synchronizeIdentityPreferences(profileId: string | undefined) { - const client = this.gatewayConnected ? this.gatewayClient : null; - const advertised = - this.context && - isGatewayMethodAdvertised(this.context.gateway.snapshot, "users.prefs.get") === true && - isGatewayMethodAdvertised(this.context.gateway.snapshot, "users.prefs.set") === true; - const scope = - client && profileId && advertised ? `${this.gatewayConnectionEpoch}\0${profileId}` : "local"; - if (scope === this.preferenceScope) { - return; - } - this.preferenceScope = scope; - this.identityPreferences = {}; - if (!client || !profileId || !advertised) { - this.preferenceMode = "local"; - this.preferenceLoad = Promise.resolve(); - return; - } - this.preferenceMode = "loading"; - this.preferenceLoad = this.loadIdentityPreferences({ - client, - gatewayUrl: this.gatewayUrl, - scope, - }); - } - - private async loadIdentityPreferences(params: { - client: NonNullable; - gatewayUrl: string; - scope: string; - }): Promise { - try { - const result = await params.client.request("users.prefs.get", {}); - if (this.preferenceScope !== params.scope) { - return; - } - if (result.status !== "ok") { - this.preferenceMode = "local"; - return; - } - let preferences = decodeIdentityPreferences(result.entries); - const browserPreferences = loadBrowserPreferences(params.gatewayUrl); - if (result.entries[PREFS_MIGRATION_KEY] !== true) { - const missingBrowserPreferences = Object.fromEntries( - Object.entries(browserPreferences).filter( - ([agentId]) => !Object.hasOwn(preferences, agentId), - ), - ); - const migrationEntries = [ - ...Object.entries(encodeIdentityPreferences(missingBrowserPreferences)), - [PREFS_MIGRATION_KEY, true] as const, - ]; - let migrationFailed = false; - for (let offset = 0; offset < migrationEntries.length; offset += 32) { - const batch = Object.fromEntries(migrationEntries.slice(offset, offset + 32)); - let response: UsersPrefsSetResult; - try { - response = await params.client.request("users.prefs.set", { - entries: batch, - }); - } catch { - migrationFailed = true; - break; - } - if (this.preferenceScope !== params.scope) { - return; - } - if (response.status !== "ok") { - migrationFailed = true; - break; - } - Object.assign(preferences, decodeIdentityPreferences(batch)); - } - if (migrationFailed) { - preferences = { ...browserPreferences, ...preferences }; - } - } - this.identityPreferences = preferences; - this.preferenceMode = "remote"; - for (const [agentId, preference] of Object.entries(preferences)) { - replaceBrowserPreference(params.gatewayUrl, agentId, preference); - } - if (this.agentsHydrated) { - this.adoptAgentDefaults({ preserveSelectedAgent: true, preserveSelectedFolder: true }); - } - } catch { - if (this.preferenceScope === params.scope) { - this.preferenceMode = "local"; - } - } - } - - private invalidateGatewayDiscovery( - resetHostSelection: boolean, - submissionOutcome: SubmissionOutcomeReason, - ) { - this.nodesRequestToken += 1; - this.nodesHydrated = false; - this.gatewayName = ""; - this.cloudProfiles = []; - this.cloudProfilesReady = false; - this.resetCloudProfileRetry(); - this.branchesRequestToken += 1; - this.repository = { kind: "idle" }; - this.baseRef = ""; // Never carry a derived ref across a transport epoch. - this.agentsHydrated = false; - this.modelControl.invalidate(resetHostSelection); - this.attachmentDraft.abortReads(); - this.closeBrowser(); - this.cancelRestoredFolderValidation(); - this.gatewayApprovedWorkspaceRoots = []; - this.folderGatewayApproved = false; - this.resetProjectSearch(); - this.invalidateSubmission(submissionOutcome); - if (!resetHostSelection) { - return; - } - if (this.pendingCloud.sessionKey) { - // Keep the original Gateway identity so a failed teardown cannot hide a worker elsewhere. - this.pendingCloud.retryAllowed = false; - this.submissionOutcomeUnknown = submissionOutcome; - } - // A replacement client may target another Gateway. Keep the user's task, - // but retire every selection and discovery result owned by the old host. - this.agentId = ""; - this.agentSelectedByUser = false; - this.folder = ""; - this.projects = []; - this.projectRecents = undefined; - this.projectId = ""; - this.folderSelectedByUser = false; - this.preferredWorktreeRestore = false; - this.worktreeSelectedByUser = false; - this.worktree = false; - this.visibility = "normal"; - this.worktreeName = ""; - this.baseRefEditGeneration += 1; - this.nodes = []; - this.execNode = ""; - this.cloudProfileId = ""; - this.error = null; - } - - private retryPendingCatalogTarget() { - if (this.catalogRetrying) { - return; - } - if ( - !this.gatewayConnected || - !catalog.isTarget(this.data) || - catalog.isResolvedTarget(this.data) - ) { - globalThis.clearTimeout(this.catalogRetryTimer); - this.catalogRetryTimer = undefined; - this.catalogRetryScope = ""; - this.catalogRetryAttempt = 0; - return; - } - const retryScope = `${this.gatewayConnectionEpoch}:${catalog.routeKey(this.data)}`; - if (this.catalogRetryScope !== retryScope) { - globalThis.clearTimeout(this.catalogRetryTimer); - this.catalogRetryTimer = undefined; - this.catalogRetryScope = retryScope; - this.catalogRetryAttempt = 0; - } - if (this.catalogRetryTimer || this.catalogRetryAttempt >= CATALOG_RETRY_DELAYS_MS.length) { - return; - } - const delayMs = CATALOG_RETRY_DELAYS_MS[this.catalogRetryAttempt]; - this.catalogRetryAttempt += 1; - this.catalogRetryTimer = globalThis.setTimeout(() => { - this.catalogRetryTimer = undefined; - if ( - this.catalogRetryScope !== retryScope || - !this.gatewayConnected || - !catalog.isTarget(this.data) || - catalog.isResolvedTarget(this.data) - ) { - return; - } - const revalidation = this.context?.revalidate("new-session"); - if (!revalidation) { - return; - } - void revalidation - .catch(() => undefined) - .then(() => this.updateComplete) - .then(() => this.retryPendingCatalogTarget()); - }, delayMs); } handleEvent(event: Event) { @@ -627,7 +182,6 @@ class NewSessionPage extends OpenClawLightDomElement { const restoreFocus = event.composedPath().includes(picker); keyEvent.preventDefault(); picker.open = false; - // Closing details does not move focus out of its now-hidden controls. if (restoreFocus) { picker.querySelector("summary")?.focus(); } @@ -642,8 +196,6 @@ class NewSessionPage extends OpenClawLightDomElement { override connectedCallback() { super.connectedCallback(); - // /new renders chat controls without ChatPane, so the route owns pointer - // and Escape light-dismissal for both picker popovers. document.addEventListener("keydown", this, true); document.addEventListener("pointerdown", this, true); } @@ -652,59 +204,40 @@ class NewSessionPage extends OpenClawLightDomElement { document.removeEventListener("keydown", this, true); document.removeEventListener("pointerdown", this, true); this.subscriptions.clear(); - // This invalidates submitRequestToken before payload release below, so a - // late sessions.create result cannot navigate with attachments we no longer own. - this.invalidateGatewayDiscovery( + this.gateway.invalidateDiscovery( true, - resolveSubmissionOutcomeReason({ - gatewayIdentityChanged: false, - cloudDraftOwned: Boolean(this.pendingCloud.sessionKey), - }), + this.submission.pendingCloud.sessionKey ? "cloud-interrupted" : "gateway-changed", ); - this.gatewaySource = null; - this.gatewayClient = null; - this.gatewayConnected = false; - this.gatewayConnectionEpoch = 0; - this.catalogRetryScope = ""; - this.catalogRetryAttempt = 0; - globalThis.clearTimeout(this.catalogRetryTimer); - this.catalogRetryTimer = undefined; - this.attachmentDraft.reset({ release: true }); - this.composerTextarea.disconnect(); - void this.gatewayNameTask.run([null, false, -1]); - void this.projectsTask.run([null, false, -1]); - void this.projectSearchTask.run([null, false, "", -1]); - void this.cloudProfileTask.run([null, -1, false, ""]); - this.resetCloudProfileRetry(); + this.gateway.disconnect(); + this.browser.disconnect(); + this.submission.disconnect(); super.disconnectedCallback(); } override updated() { - this.retryPendingCatalogTarget(); - this.modelControl.loadCatalogTargets( + this.gateway.retryPendingCatalogTarget(); + this.place.modelControl.loadCatalogTargets( this.context, - this.agentId, + this.place.agentId, this.context?.config.current.cliAgentsEnabled === true && !catalog.isTarget(this.data), ); const agentState = this.context?.agents.state; const agentsReady = Boolean( - this.gatewayConnected && - this.gatewayClient && + this.gateway.connected && + this.gateway.client && agentState?.connected && - agentState.client === this.gatewayClient && - this.agents().length > 0, + agentState.client === this.gateway.client && + this.place.agents().length > 0, ); const openKey = this.data ? catalog.routeKey(this.data) : catalog.routeKeyFromSearch(window.location.search); const resolvedAgentId = this.data?.agentId ?? ""; if (this.openedFor !== openKey) { - // Route changes reset every source-owned control. Only text typed after - // the URL changed belongs to the destination and may survive that reset. - const ownedMessage = this.messageOwnerKey === openKey ? this.message : ""; + const ownedMessage = this.messageOwnerKey === openKey ? this.submission.message : ""; this.openedFor = openKey; this.openedAgentId = resolvedAgentId; - this.agentsHydrated = agentsReady; + this.place.setAgentsHydrated(agentsReady); this.resetDraft(); if (ownedMessage) { this.setMessage(ownedMessage, openKey); @@ -712,1346 +245,55 @@ class NewSessionPage extends OpenClawLightDomElement { return; } if (this.openedAgentId !== resolvedAgentId) { - // The route named the target agent after the draft opened, so the page is - // still holding the fallback agent it adopted while the id was unknown. this.openedAgentId = resolvedAgentId; - this.agentsHydrated = false; + this.place.setAgentsHydrated(false); } - // A hard reload can land here before agents.list resolves. Once the list - // arrives, adopt only agent-derived defaults; a full reset would discard - // anything the user already typed while the list was loading. - if (!this.agentsHydrated && agentsReady) { - this.agentsHydrated = true; - this.adoptAgentDefaults({ preserveSelectedAgent: true, preserveSelectedFolder: true }); - } - } - - private readonly handleCatalogRetry = () => { - if ( - this.catalogRetrying || - !this.gatewayConnected || - !catalog.isTarget(this.data) || - catalog.isResolvedTarget(this.data) - ) { - return; - } - const revalidation = this.context?.revalidate("new-session"); - if (!revalidation) { - return; - } - globalThis.clearTimeout(this.catalogRetryTimer); - this.catalogRetryTimer = undefined; - this.catalogRetrying = true; - void revalidation - .catch(() => undefined) - .then(() => this.updateComplete) - .finally(() => { - this.catalogRetrying = false; - this.retryPendingCatalogTarget(); + if (!this.place.agentsHydrated && agentsReady) { + this.place.setAgentsHydrated(true); + this.place.adoptAgentDefaults({ + preserveSelectedAgent: true, + preserveSelectedFolder: true, }); - }; - - private agents() { - return listSelectableAgents(this.context?.agents.state.agentsList?.agents ?? []); - } - - private selectedAgent() { - const agentId = normalizeAgentId(this.agentId); - return this.agents().find((agent) => normalizeAgentId(agent.id) === agentId); - } - - private selectedProject() { - return this.projects.find((project) => project.id === this.projectId); - } - - private get projectSearchResult(): ProjectsSearchRemoteResult | null { - return this.projectSearchTask.status === TaskStatus.COMPLETE && - this.debouncedProjectQuery === this.projectQuery.trim() - ? (this.projectSearchTask.value ?? null) - : null; - } - - private get projectSearchLoading(): boolean { - return ( - this.debouncedProjectQuery.length >= 2 && - this.debouncedProjectQuery === this.projectQuery.trim() && - this.projectSearchTask.status === TaskStatus.PENDING - ); - } - - private get projectSearchError(): string | null { - if ( - this.projectSearchTask.status !== TaskStatus.ERROR || - this.debouncedProjectQuery !== this.projectQuery.trim() - ) { - return null; - } - const error = this.projectSearchTask.error; - return error instanceof Error ? error.message : String(error); - } - - private clearProjectSearchTimer() { - globalThis.clearTimeout(this.projectSearchTimer); - this.projectSearchTimer = undefined; - } - - private resetProjectSearch() { - this.clearProjectSearchTimer(); - this.projectCloneRequestToken += 1; - this.projectQuery = ""; - this.debouncedProjectQuery = ""; - this.projectCloneBusy = false; - this.projectCloneError = null; - } - - private changeProjectQuery(query: string) { - this.projectQuery = query; - this.projectCloneError = null; - this.clearProjectSearchTimer(); - this.debouncedProjectQuery = ""; - void this.projectSearchTask.run([null, false, "", this.gatewayConnectionEpoch]); - const normalized = query.trim(); - if ( - normalized.length < 2 || - projectCloneInput(normalized) || - !this.gatewayConnected || - !this.gatewayClient || - !this.context || - !canCallGatewayMethod(this.context.gateway.snapshot, "projects.searchRemote", "operator.read") - ) { - return; - } - const client = this.gatewayClient; - const connectionEpoch = this.gatewayConnectionEpoch; - this.projectSearchTimer = globalThis.setTimeout(() => { - this.projectSearchTimer = undefined; - if (client !== this.gatewayClient || connectionEpoch !== this.gatewayConnectionEpoch) { - return; - } - this.debouncedProjectQuery = normalized; - void this.projectSearchTask.run([client, true, normalized, connectionEpoch]); - }, PROJECT_SEARCH_DEBOUNCE_MS); - } - - private async addRemoteProject(gitUrl: string) { - const client = this.gatewayClient; - if ( - !client || - !this.gatewayConnected || - this.projectCloneBusy || - !this.context || - !canCallGatewayMethod(this.context.gateway.snapshot, "projects.add", "operator.write") - ) { - return; - } - const requestId = ++this.projectCloneRequestToken; - const connectionEpoch = this.gatewayConnectionEpoch; - this.projectCloneBusy = true; - this.projectCloneError = null; - try { - const project = await client.request( - "projects.add", - { gitUrl }, - { timeoutMs: null }, - ); - if ( - requestId !== this.projectCloneRequestToken || - client !== this.gatewayClient || - connectionEpoch !== this.gatewayConnectionEpoch - ) { - return; - } - await this.projectsTask.run([client, true, connectionEpoch]); - if ( - requestId !== this.projectCloneRequestToken || - client !== this.gatewayClient || - connectionEpoch !== this.gatewayConnectionEpoch - ) { - return; - } - this.selectProjectId(project.id); - this.closeBrowser(); - } catch (error) { - if (requestId === this.projectCloneRequestToken && client === this.gatewayClient) { - this.projectCloneError = error instanceof Error ? error.message : String(error); - } - } finally { - if (requestId === this.projectCloneRequestToken) { - this.projectCloneBusy = false; - } } } - private execNodes(): DraftNode[] { - return this.nodes.filter((node) => node.canExec); - } - - private isAdmin(): boolean { - return hasOperatorAdminAccess(this.context?.gateway.snapshot.hello?.auth ?? null); - } - - private canWrite(): boolean { - return hasOperatorWriteAccess(this.context?.gateway.snapshot.hello?.auth ?? null); - } - - private showStartInTerminal(): boolean { - const context = this.context; - return Boolean( - context && - catalog.isTarget(this.data) && - this.data?.startTerminal && - context.config.current.cliAgentsEnabled === true && - isTerminalAvailable( - context.gateway.snapshot, - context.config.current.terminalEnabled ?? false, - ), - ); - } - - private canStartAsDraft(): boolean { - return canStartSessionAsDraft({ - allowedVisibilities: this.context?.gateway.snapshot.hello?.policy?.allowedSessionVisibilities, - hasMultipleIdentities: - this.context?.gateway.snapshot.hello?.policy?.hasMultipleSessionSharingIdentities, - }); - } - - private workspacePath(): string { - return normalizeOptionalString(this.selectedAgent()?.workspace) ?? ""; - } - - private knownWorkspaceRoots(): string[] { - const configuredWorkspace = this.workspacePath(); - return configuredWorkspace - ? [configuredWorkspace, ...this.gatewayApprovedWorkspaceRoots] - : this.gatewayApprovedWorkspaceRoots; - } - - private recordGatewayApprovedListing(listing: FsListDirResult) { - if (this.isAdmin()) { - return; - } - const roots = new Set(this.gatewayApprovedWorkspaceRoots); - roots.add(listing.path); - if (listing.parent) { - roots.add(listing.parent); - } - if (roots.size !== this.gatewayApprovedWorkspaceRoots.length) { - this.gatewayApprovedWorkspaceRoots = [...roots]; - } - } - - private usesCustomFolder(): boolean { - if (this.projectId) { - return false; - } - const folder = this.folder.trim(); - return Boolean(folder) && folder !== this.workspacePath(); - } - - private folderSubmissionMode(): "blocked" | "approved" | "server" { - if (this.projectId) { - return this.selectedProject() ? "approved" : "blocked"; - } - if (this.restoredFolderValidation !== "none") { - return "blocked"; - } - if ( - !this.usesCustomFolder() || - this.isAdmin() || - this.folderGatewayApproved || - isKnownWorkspacePath(this.knownWorkspaceRoots(), this.folder) - ) { - return "approved"; - } - // Free-typed paths still reach sessions.create so the Gateway can return - // the authoritative missing-scope error instead of the UI dead-ending. - return "server"; - } - - private buildCreateParamsForAccess( - visibility: NewSessionVisibility = this.visibility, - ): Record { - return buildDraftSessionCreateParams({ - agentId: this.agentId, - message: "", - model: this.modelControl.selected, - thinkingLevel: this.modelControl.thinkingLevel, - visibility, - projectId: this.projectId, - worktree: this.worktree, - baseRef: this.baseRef, - worktreeName: this.worktreeName, - cwd: this.folder, - workspace: this.workspacePath(), - execNode: this.execNode, - catalogId: this.data?.catalogId, - }); - } - - private submissionAccess( - createParams: Record = this.pendingCloud.createParams ?? - this.buildCreateParamsForAccess(), - ): SessionMethodAccess { - const gateway = this.context?.gateway.snapshot; - const pendingCloud = Boolean(this.pendingCloud.sessionKey); - if (!pendingCloud || this.pendingCloud.phase === "creating") { - const createAccess = readSessionMethodAccess(gateway, { - method: "sessions.create", - params: createParams, - }); - if (!createAccess.allowed || !this.cloudProfileForSubmission()) { - return createAccess; - } - } - return readSessionMethodAccess(gateway, { - method: "sessions.dispatch", - requiredScope: "operator.admin", - }); - } - - private submitDisabledReason(): string | undefined { - const access = this.submissionAccess(); - return access.allowed ? undefined : access.reason; - } - - private terminalStartAccess(): SessionMethodAccess { - const gateway = this.context?.gateway.snapshot; - const terminalAccess = readSessionMethodAccess(gateway, { - method: "sessions.catalog.startTerminal", - requiredScope: "operator.admin", - }); - if (!terminalAccess.allowed || !this.worktree) { - return terminalAccess; - } - return readSessionMethodAccess(gateway, { - method: "worktrees.create", - requiredScope: "operator.admin", - }); - } - - private terminalStartDisabledReason(): string | undefined { - const access = this.terminalStartAccess(); - return access.allowed ? undefined : access.reason; - } - - private incognitoDisabledReason(): string | undefined { - const access = readSessionMethodAccess(this.context?.gateway.snapshot, { - method: "sessions.create", - params: this.buildCreateParamsForAccess("incognito"), - }); - return access.allowed ? undefined : access.reason; - } - - private preference(): NewSessionPreference | null { - if (catalog.isTarget(this.data) || this.pendingCloud.sessionKey) { - return null; - } - return this.preferenceMode === "remote" - ? (this.identityPreferences[normalizeAgentId(this.agentId)] ?? null) - : loadNewSessionPreference(this.gatewayUrl, this.agentId); - } - - private persistPreference(patch: NewSessionPreference) { - if (catalog.isTarget(this.data) || this.pendingCloud.sessionKey) { - return; - } - const agentId = normalizeAgentId(this.agentId); - const nextPatch = { - workspace: this.workspacePath(), - ...patch, - }; - if (this.preferenceMode === "local") { - patchNewSessionPreference(this.gatewayUrl, agentId, nextPatch); - return; - } - const scope = this.preferenceScope; - const client = this.gatewayClient; - const gatewayUrl = this.gatewayUrl; - const write = async () => { - await this.preferenceLoad; - if (!client || this.preferenceScope !== scope) { - return; - } - if (this.preferenceMode === "local") { - patchNewSessionPreference(gatewayUrl, agentId, nextPatch); - return; - } - const next = { ...this.identityPreferences[agentId], ...nextPatch }; - try { - const result = await client.request("users.prefs.set", { - entries: encodeIdentityPreferences({ [agentId]: next }), - }); - if (result.status !== "ok" || this.preferenceScope !== scope) { - return; - } - this.identityPreferences = { ...this.identityPreferences, [agentId]: next }; - replaceBrowserPreference(gatewayUrl, agentId, next); - } catch { - // Gateway state is authoritative for identified users; retain the last mirrored value. - } - }; - this.preferenceWrite = this.preferenceWrite.then(write, write); - } - - private cancelRestoredFolderValidation() { - this.restoredFolderValidationToken += 1; - this.restoredFolderValidation = "none"; - } - - private restoreWorkspaceFolder() { - this.restoredFolderValidation = "none"; - this.folderGatewayApproved = false; - if (this.error === t("newSession.browserLoadFailed")) { - this.error = null; - } - this.folder = this.workspacePath(); - this.worktree = false; - this.preferredWorktreeRestore = false; - this.persistPreference({ folder: this.folder, worktree: false }); - this.maybeLoadBranches(); - } - - private validateRestoredFolder(folder: string) { - const snapshot = this.context?.gateway.snapshot; - const client = snapshot?.client; - if (snapshot?.phase !== "connected" || !client) { - this.restoreWorkspaceFolder(); - return; - } - const requestId = ++this.restoredFolderValidationToken; - this.restoredFolderValidation = "checking"; - void client - .request("fs.listDir", { path: folder }) - .then((result) => { - if ( - requestId !== this.restoredFolderValidationToken || - this.folderSelectedByUser || - this.folder !== folder - ) { - return; - } - this.recordGatewayApprovedListing(result); - this.folderGatewayApproved = !this.isAdmin(); - this.restoredFolderValidation = "none"; - if (this.error === t("newSession.browserLoadFailed")) { - this.error = null; - } - this.maybeLoadBranches(); - }) - .catch((error: unknown) => { - if ( - requestId !== this.restoredFolderValidationToken || - this.folderSelectedByUser || - this.folder !== folder - ) { - return; - } - if (!this.isAdmin() || isMissingRestoredFolderError(error)) { - this.restoreWorkspaceFolder(); - return; - } - this.restoredFolderValidation = "failed"; - this.error = t("newSession.browserLoadFailed"); - }); - } - - private adoptAgentDefaults( - options: { preserveSelectedAgent?: boolean; preserveSelectedFolder?: boolean } = {}, + private invalidateGatewayDiscovery( + resetHostSelection: boolean, + submissionOutcome: SubmissionOutcomeReason, ) { - const agents = this.agents(); - const configuredDefault = this.context?.agents.state.agentsList?.defaultId; - const fallback = agents.some((agent) => agent.id === configuredDefault) - ? (configuredDefault ?? "main") - : (agents[0]?.id ?? "main"); - const keepSelectedAgent = - options.preserveSelectedAgent && this.agentSelectedByUser && Boolean(this.selectedAgent()); - if (!keepSelectedAgent) { - this.agentId = catalog.resolveAgentId(this.data, agents, fallback); - this.agentSelectedByUser = false; + this.place.invalidateGatewayDiscovery(resetHostSelection); + this.submission.attachmentDraft.abortReads(); + this.submission.invalidate(submissionOutcome); + if (resetHostSelection && this.submission.pendingCloud.sessionKey) { + this.submission.markPendingCloudUnavailable(submissionOutcome); } - const preference = this.preference(); - const keepSelectedFolder = options.preserveSelectedFolder && this.folderSelectedByUser; - // A node cwd belongs to node discovery, and a locked cloud-recovery draft - // shows its staged repo; neither may be replaced by a workspace refresh. - if (!this.execNode && !keepSelectedFolder && !this.pendingCloud.sessionKey) { - const workspace = this.workspacePath(); - const storedFolder = preference?.folder ?? ""; - // An old agent workspace path is not a custom folder. If the configured - // workspace moved, use the current value instead of reviving the stale path. - const storedWorkspaceMoved = - Boolean(storedFolder) && - storedFolder === preference?.workspace && - preference.workspace !== workspace; - const storedFolderUsable = Boolean(storedFolder) && !storedWorkspaceMoved; - this.folder = storedFolderUsable ? storedFolder : workspace; - this.folderGatewayApproved = false; - this.folderSelectedByUser = false; - this.preferredWorktreeRestore = preference?.worktree === true; - this.worktreeSelectedByUser = false; - if (storedWorkspaceMoved) { - this.persistPreference({ folder: workspace }); - } - } - if (keepSelectedFolder && !this.execNode && !this.pendingCloud.sessionKey && this.agentId) { - // A folder picked before agents.list resolves has no stable preference - // owner. Persist it only after the final agent id is known. - this.persistPreference({ folder: this.folder, worktree: this.worktree }); - } - void this.loadNodes(); - this.modelControl.load(this.context, this.agentId, !catalog.isTarget(this.data), { - agent: this.selectedAgent(), - preference, - }); - if ( - !this.folderSelectedByUser && - this.folder !== this.workspacePath() && - !this.execNode && - !this.pendingCloud.sessionKey - ) { - this.validateRestoredFolder(this.folder); - } else { - this.cancelRestoredFolderValidation(); - this.maybeLoadBranches(); + if (resetHostSelection) { + this.submission.clearError(); } } private resetDraft() { - const preservePendingCloud = Boolean(this.pendingCloud.sessionKey); - this.invalidateSubmission(); - this.submissionOutcomeUnknown = preservePendingCloud - ? (this.submissionOutcomeUnknown ?? "cloud-interrupted") - : null; - this.agentSelectedByUser = false; - this.folder = ""; - this.projectId = ""; - this.resetProjectSearch(); - this.folderSelectedByUser = false; - this.folderGatewayApproved = false; - this.gatewayApprovedWorkspaceRoots = []; - this.cancelRestoredFolderValidation(); - this.preferredWorktreeRestore = false; - this.worktreeSelectedByUser = false; - this.worktree = false; - this.visibility = "normal"; - this.worktreeName = ""; - this.baseRef = ""; - this.repository = { kind: "idle" }; - this.execNode = ""; - this.modelControl.reset(); - this.attachmentDraft.reset({ release: true }); - this.cloudProfileId = ""; - if (preservePendingCloud) { - if (!this.pendingCloud.restored) { - this.pendingCloud.retryAllowed = false; - } - this.agentId = this.pendingCloud.agentId; - this.cloudProfileId = this.pendingCloud.profileId; - this.worktree = true; - this.visibility = this.pendingCloud.createParams?.incognito === true ? "incognito" : "normal"; - // Show the staged repo (not the agent workspace) while the draft is locked. - this.folder = this.pendingCloud.createParams?.cwd ?? ""; - this.pendingCloud.restored = false; - this.setMessage(this.pendingCloud.message); - this.attachmentDraft.replace(restoreChatApiAttachments(this.pendingCloud.attachments)); - } else { - this.clearPendingCloudRecovery(); - this.setMessage(""); - } - this.error = null; - this.placePopoverHiding = false; + this.place.resetDraft(); + this.submission.resetDraft(); + this.messageOwnerKey = catalog.routeKey(this.data); + this.browser.clearPopoverHiding(); this.closeAgentDropdown(); - this.closeBrowser(); - this.adoptAgentDefaults(); + this.browser.close(); + this.place.adoptAgentDefaults(); void this.updateComplete.then(() => { this.querySelector(".new-session-page__message")?.focus(); }); } private setMessage(message: string, ownerKey = catalog.routeKey(this.data)) { - this.message = message; + this.submission.setMessage(message); this.messageOwnerKey = ownerKey; } private setMessageFromUser(message: string) { - // History changes before an async route loader settles. Input accepted from - // the retained composer belongs to the browser destination, not stale data. this.setMessage(message, catalog.routeKeyFromSearch(window.location.search)); } - private invalidateSubmission(outcomeUnknown: SubmissionOutcomeReason | null = null) { - this.submitRequestToken += 1; - if (outcomeUnknown && this.submitting) { - this.submissionOutcomeUnknown = outcomeUnknown; - } - this.submitting = false; - } - - private clearPendingCloudRecovery() { - this.pendingCloud.clear(); - this.submissionOutcomeUnknown = null; - } - - private restorePendingCloudRecovery(gatewayUrl: string, recoveryScope: string) { - const recovery = this.pendingCloud.restore(gatewayUrl, recoveryScope); - if (!recovery) { - return; - } - this.agentId = recovery.agentId; - this.cloudProfileId = recovery.profileId; - this.worktree = true; - this.visibility = recovery.createParams?.incognito === true ? "incognito" : "normal"; - // Show the staged repo (not the agent workspace) while the draft is locked. - this.folder = recovery.createParams?.cwd ?? ""; - this.folderGatewayApproved = false; - this.setMessage(recovery.message); - this.attachmentDraft.replace(restoreChatApiAttachments(recovery.attachments)); - } - - private async loadNodes() { - const requestId = ++this.nodesRequestToken; - this.nodesHydrated = false; - const snapshot = this.context?.gateway.snapshot; - const client = snapshot?.client; - if (snapshot?.phase !== "connected" || !client || !this.isAdmin()) { - this.nodes = []; - this.nodesHydrated = true; - return; - } - try { - const result = await client.request<{ nodes?: unknown }>("node.list", {}); - if (requestId !== this.nodesRequestToken) { - return; - } - const nodes = readDraftNodes(result?.nodes); - this.nodes = nodes; - this.nodesHydrated = true; - if (this.execNode && !nodes.some((node) => node.nodeId === this.execNode && node.canExec)) { - // A reconnect can remove a device. Its cwd is not meaningful on the - // Gateway, so fall back to the selected agent's workspace as one unit. - this.execNode = ""; - this.folder = this.workspacePath(); - this.folderSelectedByUser = false; - this.folderGatewayApproved = false; - this.worktree = false; - this.worktreeName = ""; - this.closeBrowser(); - this.maybeLoadBranches(); - } - } catch { - if (requestId === this.nodesRequestToken) { - this.nodes = []; - this.nodesHydrated = true; - } - } - } - - private maybeLoadBranches() { - // Repository capability and branch data belong to one Gateway folder. - // Reset them together so a previous checkout can never leak into create params. - const requestId = ++this.branchesRequestToken; - const restoreWorktree = this.preferredWorktreeRestore && !this.worktreeSelectedByUser; - const baseRefEditGeneration = this.baseRefEditGeneration; - this.repository = { kind: "idle" }; - this.baseRef = ""; - const selectedProject = this.selectedProject(); - if (this.execNode) { - this.preferredWorktreeRestore = false; - return; - } - if (selectedProject && !selectedProject.repoRoot) { - this.preferredWorktreeRestore = false; - return; - } - const repoRoot = selectedProject?.repoRoot ?? (this.folder.trim() || this.workspacePath()); - const agent = this.selectedAgent(); - const usesWorkspace = !selectedProject && repoRoot === this.workspacePath(); - if (!repoRoot) { - this.preferredWorktreeRestore = false; - return; - } - if (usesWorkspace && agent?.workspaceGit !== true) { - this.repository = { kind: "direct", repoRoot }; - const rejectedWorktree = !this.cloudProfileId && (this.worktree || restoreWorktree); - if (!this.cloudProfileId) { - this.worktree = false; - } - this.preferredWorktreeRestore = false; - if (rejectedWorktree) { - this.persistPreference({ worktree: false }); - } - return; - } - const snapshot = this.context?.gateway.snapshot; - const client = snapshot?.client; - if (snapshot?.phase !== "connected" || !client) { - this.preferredWorktreeRestore = false; - return; - } - this.repository = { kind: "checking", repoRoot }; - void client - .request("worktrees.branches", { - repoRoot, - includeRepositoryStatus: true, - }) - .then((result) => { - if (requestId !== this.branchesRequestToken) { - return; - } - if (result?.repositoryStatus !== "git") { - this.repository = { - kind: result?.repositoryStatus === "not_git" ? "direct" : "unavailable", - repoRoot, - }; - if (result?.repositoryStatus === "not_git") { - const rejectedWorktree = !this.cloudProfileId && (this.worktree || restoreWorktree); - if (!this.cloudProfileId) { - this.worktree = false; - } - if (rejectedWorktree) { - this.persistPreference({ worktree: false }); - } - } else if (restoreWorktree && !this.worktreeSelectedByUser && this.worktreeAvailable()) { - // An inconclusive lookup cannot disprove a stored worktree choice, but - // it may only be restored while the toggle stays usable: an unavailable - // repository disables that control, and a box the user cannot clear - // would strand the draft behind a permanently disabled submit. - this.worktree = true; - } - this.preferredWorktreeRestore = false; - return; - } - this.repository = { - kind: "git", - repoRoot, - branches: result.branches, - ...(result.defaultBranch ? { defaultBranch: result.defaultBranch } : {}), - ...(result.headBranch ? { headBranch: result.headBranch } : {}), - }; - if (restoreWorktree && !this.worktreeSelectedByUser && !this.execNode) { - this.worktree = true; - } - this.preferredWorktreeRestore = false; - // Discovery supplies a default only while the field is untouched; - // a user edit made during the request remains authoritative. - if (baseRefEditGeneration === this.baseRefEditGeneration) { - this.baseRef = result.defaultBranch ?? result.headBranch ?? ""; - } - }) - .catch(() => { - if (requestId !== this.branchesRequestToken) { - return; - } - this.repository = { kind: "unavailable", repoRoot }; - if (restoreWorktree && !this.worktreeSelectedByUser && this.worktreeAvailable()) { - this.worktree = true; - } - this.preferredWorktreeRestore = false; - }); - } - - private worktreeAvailable(): boolean { - if (this.execNode) { - return false; - } - if (this.selectedProject()?.repoRoot) { - return true; - } - if (this.repository.kind === "git") { - return true; - } - return ( - this.repository.kind === "unavailable" && - this.repository.repoRoot === this.workspacePath() && - this.selectedAgent()?.workspaceGit === true - ); - } - - private cloudProfileForSubmission(): string { - return this.pendingCloud.sessionKey ? this.pendingCloud.profileId : this.cloudProfileId; - } - - private cloudRuntimeUnsupportedReason(): string | undefined { - const runtime = this.modelControl.resolveAgentRuntimeId({ - agent: this.selectedAgent(), - context: this.context, - }); - return runtime && runtime !== "openclaw" - ? t("newSession.cloudRequiresOpenClawRuntime", { runtime }) - : undefined; - } - - private cloudDisabledReason(): string | undefined { - const runtimeReason = this.cloudRuntimeUnsupportedReason(); - if (runtimeReason) { - return runtimeReason; - } - if (this.repository.kind === "checking") { - return t("newSession.checkingGit"); - } - if (this.repository.kind === "unavailable" && !this.worktreeAvailable()) { - return t("newSession.gitCheckUnavailable"); - } - return this.worktreeAvailable() ? undefined : t("newSession.cloudRequiresWorktree"); - } - - private canSubmit(kind: "session" | "terminal" = "session"): boolean { - const pendingCloud = Boolean(this.pendingCloud.sessionKey); - const cloudProfileId = this.cloudProfileForSubmission(); - const message = pendingCloud ? this.pendingCloud.message : this.message.trim(); - const hasAttachments = pendingCloud - ? Boolean(this.pendingCloud.attachments?.length) - : this.attachmentDraft.attachments.length > 0; - const gateway = this.context?.gateway; - if ( - this.submitting || - this.preferenceMode === "loading" || - this.requiresModelSetup() || - this.attachmentDraft.pendingReads > 0 || - (!pendingCloud && this.submissionOutcomeUnknown) || - (kind === "session" && !message && !hasAttachments) || - gateway?.snapshot.phase !== "connected" || - !gateway.snapshot.client - ) { - return false; - } - const access = kind === "terminal" ? this.terminalStartAccess() : this.submissionAccess(); - if (!access.allowed) { - return false; - } - if (this.folderSubmissionMode() === "blocked") { - return false; - } - // Stored model and worktree choices are provisional until their current - // Gateway metadata confirms they still exist. Do not let a fast submit - // silently replace either preference with the server default. - if (this.modelControl.isRestoringPreference() || this.preferredWorktreeRestore) { - return false; - } - if (pendingCloud) { - return Boolean( - this.pendingCloud.retryAllowed && - gateway.snapshot.client.recoveryScopeReady && - cloudProfileId && - this.pendingCloud.agentId && - this.pendingCloud.gatewayUrl === gateway.connection.gatewayUrl && - this.pendingCloud.recoveryScope === gateway.snapshot.client?.recoveryScope && - this.isAdmin(), - ); - } - // Pre-hydration the selection is a provisional fallback; submitting then - // would create the session under the wrong agent. - if (this.agents().length === 0) { - return false; - } - if (!catalog.allowsSelectedAgent(this.data, this.selectedAgent())) { - return false; - } - if ( - this.execNode && - (!this.nodesHydrated || !this.execNodes().some((node) => node.nodeId === this.execNode)) - ) { - return false; - } - if ( - cloudProfileId && - (!this.isAdmin() || - !gateway.snapshot.client.recoveryScope || - !gateway.snapshot.client.recoveryScopeReady || - !this.cloudProfilesReady || - this.cloudProfileTask.status === TaskStatus.PENDING || - !this.worktree || - !this.cloudProfiles.some((profile) => profile.id === cloudProfileId) || - Boolean(this.cloudRuntimeUnsupportedReason())) - ) { - return false; - } - if (this.execNode && this.worktree) { - return false; - } - if (this.worktree && !this.worktreeAvailable()) { - return false; - } - if (this.worktree && !isWorktreeNameValid(this.worktreeName)) { - return false; - } - if (kind === "terminal" && !(this.folder.trim() || this.workspacePath())) { - return false; - } - return true; - } - - private requiresModelSetup(): boolean { - const selectedAgent = this.selectedAgent(); - return requiresChatModelSetup({ - catalog: - catalog.isTarget(this.data) || - Boolean(this.cloudProfileId) || - Boolean(this.pendingCloud.sessionKey), - connected: this.gatewayConnected, - agentsLoaded: this.context?.agents.state.agentsList !== null, - selectedAgentFound: selectedAgent !== undefined, - agentModel: selectedAgent?.model?.primary, - }); - } - - private closeOpenDropdowns() { - for (const dropdown of this.querySelectorAll( - "wa-dropdown[open]", - )) { - dropdown.open = false; - } - } - - private async submit() { - const context = this.context; - if (!context || !this.canSubmit()) { - return; - } - const pendingCloud = Boolean(this.pendingCloud.sessionKey); - const message = pendingCloud ? this.pendingCloud.message : this.message.trim(); - const attachments = this.attachmentDraft.attachments; - const apiAttachments = pendingCloud - ? this.pendingCloud.attachments - : buildChatApiAttachments(attachments); - const submissionAgentId = pendingCloud - ? this.pendingCloud.agentId - : normalizeAgentId(this.agentId); - const submissionGatewayUrl = pendingCloud - ? this.pendingCloud.gatewayUrl - : context.gateway.connection.gatewayUrl; - const submissionClient = context.gateway.snapshot.client; - if (!submissionClient || !context.gateway.snapshot.hello) { - return; - } - const submissionRecoveryScope = pendingCloud - ? this.pendingCloud.recoveryScope - : submissionClient.recoveryScope; - const requestId = ++this.submitRequestToken; - const submittedAt = Date.now(); - this.submitting = true; - this.error = null; - // Retire hidden pickers before their late requests can mutate this submitted draft. - this.closeBrowser(); - this.closeOpenDropdowns(); - try { - const cloudProfileId = this.cloudProfileForSubmission(); - // Draft mode can go stale if sharing policy changed since it was selected. - const draftRetired = this.visibility === "draft" && !this.canStartAsDraft(); - const createParams = buildDraftSessionCreateParams({ - agentId: this.agentId, - message: cloudProfileId ? "" : message, - model: this.modelControl.selected, - thinkingLevel: this.modelControl.thinkingLevel, - visibility: draftRetired ? "normal" : this.visibility, - attachments: cloudProfileId ? undefined : apiAttachments, - projectId: this.projectId, - worktree: this.worktree, - baseRef: this.baseRef, - worktreeName: this.worktreeName, - cwd: this.folder, - workspace: this.workspacePath(), - execNode: this.execNode, - catalogId: this.data?.catalogId, - }); - const cloudCreateParams = cloudProfileId - ? pendingCloud - ? this.pendingCloud.createParams - : this.pendingCloud.stageCreate({ - agentId: submissionAgentId, - profileId: cloudProfileId, - message, - attachments: apiAttachments, - gatewayUrl: submissionGatewayUrl, - recoveryScope: submissionRecoveryScope, - createParams, - persistent: this.visibility !== "incognito", - }) - : undefined; - const requestAccess = this.submissionAccess(cloudCreateParams ?? createParams); - if (!requestAccess.allowed) { - this.error = requestAccess.reason; - return; - } - if (cloudProfileId && !pendingCloud && !cloudCreateParams) { - this.error = t("newSession.cloudStartFailed", { - error: "cloud recovery storage is unavailable", - }); - return; - } - const submissionCloudRecovery = cloudProfileId ? this.pendingCloud.capture() : null; - if (cloudProfileId && !submissionCloudRecovery) { - this.error = t("newSession.cloudStartFailed", { - error: "cloud recovery storage is unavailable", - }); - return; - } - const recoveryOwnerKey = submissionCloudRecovery?.sessionKey ?? ""; - const ownsSubmissionRecovery = () => - this.pendingCloud.owns(submissionGatewayUrl, submissionRecoveryScope, recoveryOwnerKey); - const isSubmissionLifecycleCurrent = () => - this.isConnected && - submissionClient.recoveryScopeReady && - requestId === this.submitRequestToken && - this.gatewayClient === submissionClient && - this.gatewayUrl === submissionGatewayUrl && - this.gatewayRecoveryScope === submissionRecoveryScope; - const result = - pendingCloud && this.pendingCloud.phase !== "creating" - ? { key: this.pendingCloud.sessionKey, initialRun: { status: "idle" as const } } - : await context.sessions.createResult(cloudCreateParams ?? createParams, { - reconciliation: "background", - }); - if (requestId !== this.submitRequestToken && !cloudProfileId) { - return; - } - if (!result) { - if (requestId !== this.submitRequestToken) { - return; - } - this.error = context.sessions.state.error ?? t("newSession.createFailed"); - return; - } - if (cloudProfileId && submissionCloudRecovery) { - if ( - submissionCloudRecovery.phase === "creating" && - (!isSubmissionLifecycleCurrent() || !ownsSubmissionRecovery()) - ) { - const cleanupError = await deleteCloudDraftSession( - submissionClient, - result.key, - submissionAgentId, - ); - if (cleanupError) { - this.pendingCloud.promoteToDispatching(result.key); - this.pendingCloud.retryAllowed = true; - this.error = t("newSession.cloudStartFailed", { error: cleanupError }); - } else { - this.clearPendingCloudRecovery(); - } - return; - } - if ( - submissionCloudRecovery.phase === "creating" && - isSubmissionLifecycleCurrent() && - ownsSubmissionRecovery() - ) { - if (!this.pendingCloud.promoteToDispatching(result.key)) { - this.error = t("newSession.cloudStartFailed", { - error: "cloud recovery storage is unavailable", - }); - return; - } - } - const recovery = this.pendingCloud.capture(); - if (!recovery || recovery.phase === "creating") { - this.error = t("newSession.cloudStartFailed", { - error: "cloud recovery storage is unavailable", - }); - return; - } - if (requestId !== this.submitRequestToken) { - return; - } - context.cloudStartup.start({ - recovery, - persistRecovery: this.pendingCloud.persistent, - recovering: pendingCloud, - createdAt: submittedAt, - }); - if ( - requestId !== this.submitRequestToken || - !isSubmissionLifecycleCurrent() || - !this.pendingCloud.owns( - submissionGatewayUrl, - submissionRecoveryScope, - recovery.sessionKey, - ) - ) { - return; - } - // The coordinator captured durable attachment bytes and recovery identity. - // Release only this route's draft before navigation unmounts it. - this.pendingCloud.reset(); - this.attachmentDraft.clearAfterSubmit(true); - selectApplicationSession({ - selection: context.agentSelection, - gateway: context.gateway, - sessionKey: result.key, - agentId: submissionAgentId, - }); - context.navigate( - "chat", - sessionNavigationTarget({ - context, - face: "chat", - sessionKey: result.key, - agentId: this.agentId, - }).options, - ); - return; - } - if (requestId !== this.submitRequestToken) { - return; - } - const handedOffAttachments = - result.initialRun.status === "rejected" && - retainRejectedInitialTurn({ - agentId: this.agentId, - attachments, - context, - error: result.initialRun.error, - message, - sessionKey: result.key, - }); - if (result.initialRun.status === "started") { - prepareInitialUserMessageHandoff( - context.initialUserMessage, - result.key, - { - text: message, - attachments, - createdAt: submittedAt, - }, - submissionClient, - { - runId: result.initialRun.runId, - messageSeq: result.initialRun.messageSeq, - }, - ); - } - this.attachmentDraft.clearAfterSubmit(!handedOffAttachments); - if (requestId !== this.submitRequestToken) { - return; - } - selectApplicationSession({ - selection: context.agentSelection, - gateway: context.gateway, - sessionKey: result.key, - agentId: submissionAgentId, - }); - context.navigate( - "chat", - sessionNavigationTarget({ - context, - face: "chat", - sessionKey: result.key, - agentId: this.agentId, - }).options, - ); - } finally { - if (requestId === this.submitRequestToken) { - this.submitting = false; - } - } - } - - private async startInTerminal() { - const context = this.context; - const client = context?.gateway.snapshot.client; - const catalogId = this.data?.catalogId.trim() ?? ""; - const agentId = normalizeAgentId(this.agentId); - if (!context || !client || !catalogId || !agentId || !this.canSubmit("terminal")) { - return; - } - const requestId = ++this.submitRequestToken; - const initialMessage = this.message.trim(); - this.submitting = true; - this.error = null; - this.closeBrowser(); - this.closeOpenDropdowns(); - try { - let cwd = this.folder.trim() || this.workspacePath(); - if (this.worktree) { - const created = await createManagedWorktree(client, { - repoRoot: cwd, - name: this.worktreeName, - baseRef: this.baseRef, - }); - if (requestId !== this.submitRequestToken || this.gatewayClient !== client) { - return; - } - cwd = created.path; - } - const result = await client.request( - "sessions.catalog.startTerminal", - { - catalogId, - ...(this.execNode ? { hostId: `node:${this.execNode}` } : {}), - agentId, - cwd, - ...(initialMessage ? { initialMessage } : {}), - }, - ); - if (requestId !== this.submitRequestToken || this.gatewayClient !== client) { - return; - } - this.setMessage(""); - openTerminalSessionInTerminal(result.sessionId); - } catch (error) { - if (requestId === this.submitRequestToken && this.gatewayClient === client) { - this.error = error instanceof Error ? error.message : String(error); - } - } finally { - if (requestId === this.submitRequestToken) { - this.submitting = false; - } - } - } - - private selectAgentId(agentId: string) { - if (this.submitting || this.pendingCloud.sessionKey || catalog.isTarget(this.data)) { - return; - } - // Re-picking the checked agent must not reset the draft (the native - // select never fired change for the same option). - if (normalizeAgentId(agentId) === normalizeAgentId(this.agentId)) { - return; - } - this.agentId = normalizeAgentId(agentId); - this.cancelRestoredFolderValidation(); - this.modelControl.reset(); - this.error = null; - this.agentSelectedByUser = true; - this.folderSelectedByUser = false; - this.folderGatewayApproved = false; - this.gatewayApprovedWorkspaceRoots = []; - this.projectId = ""; - this.preferredWorktreeRestore = false; - this.worktreeSelectedByUser = false; - this.cloudProfileId = ""; - this.worktree = false; - this.worktreeName = ""; - this.closeBrowser(); - if (this.execNode) { - // Node cwd choices are agent-scoped draft state; switching agents must - // not carry the previous agent's remote path into the next session. - this.folder = ""; - } - this.adoptAgentDefaults({ preserveSelectedAgent: true }); - } - - /** - * Loaded branch data already covers the effective Gateway repo selection. - * Branch data is always Gateway-owned: maybeLoadBranches clears and never - * requests while a node is selected, so a path match cannot cross hosts. - */ - private branchesMatchCurrentRepo(): boolean { - if (this.execNode || this.repository.kind === "idle") { - return false; - } - const repoRoot = this.folder.trim() || this.workspacePath(); - return this.repository.repoRoot === repoRoot; - } - - private applyFolder(folder: string, execNode = this.execNode, gatewayApproved = false) { - if (this.submitting || this.pendingCloud.sessionKey) { - return; - } - this.execNode = execNode; - this.projectId = ""; - this.cancelRestoredFolderValidation(); - if (execNode) { - // Node sessions run on that device; a cloud worker cannot sync a node path. - this.cloudProfileId = ""; - } - this.error = null; - this.folder = folder.trim(); - this.folderGatewayApproved = gatewayApproved && !execNode && !this.isAdmin(); - this.folderSelectedByUser = true; - this.preferredWorktreeRestore = false; - this.worktreeSelectedByUser = true; - if (this.execNode) { - this.worktree = false; - } else if (!this.cloudProfileId) { - // A newly selected Gateway folder starts direct. Git capability discovery - // may reveal the optional managed-worktree control afterward. - this.worktree = false; - } - this.worktreeName = ""; - if (!this.execNode && this.agentsHydrated) { - this.persistPreference({ folder: this.folder, worktree: this.worktree }); - } - this.maybeLoadBranches(); - } - - private selectProjectId(projectId: string) { - if (this.submitting || this.pendingCloud.sessionKey) { - return; - } - const project = this.projects.find((candidate) => candidate.id === projectId); - if (!project) { - return; - } - this.cancelRestoredFolderValidation(); - this.resetProjectSearch(); - this.projectId = project.id; - this.execNode = ""; - this.cloudProfileId = ""; - this.error = null; - this.folderSelectedByUser = false; - this.preferredWorktreeRestore = false; - this.worktreeSelectedByUser = true; - this.worktree = false; - this.worktreeName = ""; - this.maybeLoadBranches(); - } - - private selectExecNode(execNode: string) { - if (this.submitting || this.pendingCloud.sessionKey) { - return; - } - if (execNode === this.execNode && !this.cloudProfileId) { - return; - } - // Turning a cloud selection back into a plain Gateway session keeps the - // picked repo; only a host change retires the folder path. - const keepGatewayFolder = !execNode && !this.execNode; - this.cancelRestoredFolderValidation(); - const keepWorktree = keepGatewayFolder && this.worktree && this.worktreeAvailable(); - this.execNode = execNode; - this.cloudProfileId = ""; - if (!keepGatewayFolder) { - // Folder paths belong to one host; never carry a Gateway or node path to another host. - this.folder = execNode ? "" : this.workspacePath(); - this.folderSelectedByUser = false; - this.folderGatewayApproved = false; - this.projectId = ""; - } - this.worktree = keepWorktree; - this.closeBrowser(); - if (!this.branchesMatchCurrentRepo()) { - this.maybeLoadBranches(); - } - } - - private selectCloudProfile(profileId: string) { - if ( - this.submitting || - this.pendingCloud.sessionKey || - !this.worktreeAvailable() || - !this.cloudProfiles.some((profile) => profile.id === profileId) - ) { - return; - } - // worktreeAvailable() is false for node targets, so this transition always - // starts from a Gateway selection and the folder is a Gateway path. It - // stays selected: its repo is what the managed worktree checks out and the - // dispatch tunnel syncs to the cloud worker. - this.cloudProfileId = profileId; - this.projectId = ""; - this.error = null; - this.worktree = true; - this.closeBrowser(); - if (!this.branchesMatchCurrentRepo()) { - this.maybeLoadBranches(); - } - } - - private browseAvailable(): boolean { - return this.gatewayConnected && (this.isAdmin() || Boolean(this.workspacePath())); - } - private closeAgentDropdown() { const dropdown = this.querySelector( ".new-session-page__select--agent wa-dropdown", @@ -2061,217 +303,55 @@ class NewSessionPage extends OpenClawLightDomElement { } } - private closeBrowser() { - this.browserRequestToken += 1; - this.browserLoading = false; - this.browserError = null; - this.browserListing = null; - this.browserTarget = null; - this.browserProjectPath = null; - this.browserRegistering = false; - this.browserPathDraft = ""; - this.placePopoverOpen = false; - const popover = this.querySelector( - ".new-session-page__place-popover", - ); - if (popover) { - popover.open = false; + private closeOpenDropdowns() { + for (const dropdown of this.querySelectorAll( + "wa-dropdown[open]", + )) { + dropdown.open = false; } } - private guardPopoverTransition(event: Event, hiding: boolean) { - if (!hiding) { - return; - } - event.preventDefault(); - event.stopImmediatePropagation(); - } - - private restorePopoverTrigger(id: string, popoverSelector: string) { - const active = this.ownerDocument.activeElement; - const popover = this.querySelector(popoverSelector); - // Light-dismissal may already have moved focus to another control. Only - // recover when focus stayed in the closing popover or fell back to body. - if (active && active !== this.ownerDocument.body && !popover?.contains(active)) { - return; - } - this.querySelector(`#${id}`)?.focus(); - } - - private showBrowserRoot() { - this.browserRequestToken += 1; - this.browserLoading = false; - this.browserError = null; - this.browserListing = null; - this.browserTarget = null; - this.browserProjectPath = null; - this.browserRegistering = false; - this.browserPathDraft = ""; - } - - /** Use applies the live path; empty means host default, null disables. */ - private usableBrowserPath(): string | null { - const draft = this.browserPathDraft.trim(); - if (draft.length === 0) { - return ""; - } - return isAbsolutePath(draft) ? draft : null; - } - - private selectBrowserTarget(target: BrowserTarget) { - const folder = this.folder.trim(); - const matchesCurrentTarget = target.nodeId === this.execNode; - const path = matchesCurrentTarget && isAbsolutePath(folder) ? folder : undefined; - this.browserTarget = target; - this.loadBrowser(path); - } - - private loadBrowser(path: string | undefined) { - const snapshot = this.context?.gateway.snapshot; - const client = snapshot?.client; - const target = this.browserTarget; - if (snapshot?.phase !== "connected" || !client || !target) { - return; - } - // Exec-only nodes still accept a typed cwd; never probe an unsupported fs.listDir. - const targetNode = this.nodes.find((node) => node.nodeId === target.nodeId); - if (targetNode?.canExec && !targetNode.canBrowse) { - this.showBrowserRoot(); - this.browserTarget = target; - this.browserPathDraft = path ?? ""; - return; - } - const requestId = ++this.browserRequestToken; - this.browserLoading = true; - this.browserError = null; - this.browserProjectPath = null; - // Clear the previous directory immediately: keeping it clickable while the - // request is in flight would let "Use this folder" apply the stale path. - this.browserListing = null; - // Navigation owns the shown path at once, so a mid-flight "Use this - // folder" applies where the user is heading, never the directory they - // just left ("" = the host default while heading home). - this.browserPathDraft = path ?? ""; - const draftAtRequest = this.browserPathDraft; - void client - .request("fs.listDir", { - ...(path ? { path } : {}), - ...(target.nodeId ? { nodeId: target.nodeId } : {}), - }) - .then((result) => { - if (requestId !== this.browserRequestToken) { - return; - } - this.browserListing = result ?? null; - if (result) { - this.recordGatewayApprovedListing(result); - } - // Sync the head input to the listed directory unless the user typed - // while this request was in flight; their edit wins. - if (result?.path && this.browserPathDraft === draftAtRequest) { - this.browserPathDraft = result.path; - } - if (result?.path && !target.nodeId && this.isAdmin()) { - // Browse and worktree selection share the Gateway's Git-checkout verdict; - // fs.listDir stays a filesystem-only contract. - void client - .request("worktrees.branches", { - repoRoot: result.path, - includeRepositoryStatus: true, - }) - .then((branches) => { - if ( - requestId === this.browserRequestToken && - this.browserListing?.path === result.path && - branches.repositoryStatus === "git" - ) { - this.browserProjectPath = result.path; - } - }) - .catch(() => undefined); - } - }) - .catch(() => { - if (requestId !== this.browserRequestToken) { - return; - } - // A stale or mistyped folder should not strand the picker: fall back home. - if (path) { - this.loadBrowser(undefined); - return; - } - this.browserError = t("newSession.browserLoadFailed"); - }) - .finally(() => { - if (requestId === this.browserRequestToken) { - this.browserLoading = false; - } - }); - } - - private async registerBrowserProject(path: string) { - const snapshot = this.context?.gateway.snapshot; - const client = snapshot?.client; - if ( - snapshot?.phase !== "connected" || - !client || - !this.isAdmin() || - this.browserTarget?.nodeId || - this.browserProjectPath !== path || - this.browserRegistering - ) { - return; - } - const requestId = this.browserRequestToken; - const connectionEpoch = this.gatewayConnectionEpoch; - this.browserRegistering = true; - this.browserError = null; - try { - const project = await client.request("projects.register", { path }); - if (requestId !== this.browserRequestToken || client !== this.gatewayClient) { - return; - } - await this.projectsTask.run([client, true, connectionEpoch]); - if (requestId !== this.browserRequestToken || client !== this.gatewayClient) { - return; - } - this.selectProjectId(project.id); - this.closeBrowser(); - } catch (error) { - if (requestId === this.browserRequestToken && client === this.gatewayClient) { - this.browserError = error instanceof Error ? error.message : String(error); - } - } finally { - if (requestId === this.browserRequestToken) { - this.browserRegistering = false; - } - } - } - - private renderAgentSelect(agents: ReturnType) { + private renderAgentSelect() { return renderAgentSelect({ - agents, - agentId: this.agentId, - disabled: this.submitting || Boolean(this.pendingCloud.sessionKey), - onSelect: (agentId) => this.selectAgentId(agentId), + agents: this.place.agents(), + agentId: this.place.agentId, + disabled: this.submission.submitting || Boolean(this.submission.pendingCloud.sessionKey), + onSelect: (agentId) => this.place.selectAgentId(agentId), + }); + } + + private renderTargetBar() { + const agents = this.place.agents(); + return catalog.renderBar({ + data: this.data, + agentSelect: agents.length > 1 ? this.renderAgentSelect() : nothing, + placeSelect: this.renderPlaceSelect(), + retrying: this.gateway.catalogRetrying, + onRetry: this.gateway.handleCatalogRetry, }); } private renderPlaceSelect() { - const execNodes = this.execNodes(); - const cloudProfiles = catalog.isTarget(this.data) ? [] : this.cloudProfiles; - const branches = this.repository.kind === "git" ? this.repository : null; - const cloudDisabledReason = this.cloudDisabledReason(); + const execNodes = this.place.execNodes(); + const cloudProfiles = catalog.isTarget(this.data) ? [] : this.gateway.cloudProfiles; + const branches = this.place.repository.kind === "git" ? this.place.repository : null; return renderPlaceSelect({ - browseAvailable: this.browseAvailable(), - isAdmin: this.isAdmin(), - canWrite: this.canWrite(), - folder: this.folder, - workspace: this.workspacePath(), - workspaceRoots: this.knownWorkspaceRoots(), - projects: catalog.isTarget(this.data) ? [] : this.projects, - recents: catalog.isTarget(this.data) ? [] : this.projectRecents, - projectQuery: this.projectQuery, + browseAvailable: this.place.browseAvailable(), + isAdmin: this.place.isAdmin(), + canWrite: this.place.canWrite(), + folder: this.place.folder, + workspace: this.place.workspacePath(), + projects: catalog.isTarget(this.data) ? [] : this.browser.projects, + recents: catalog.isTarget(this.data) + ? [] + : this.browser.resolveProjectRecents({ + sessions: this.context?.sessions.state.result?.sessions ?? [], + workspace: this.place.workspacePath(), + workspaceRoots: this.place.knownWorkspaceRoots(), + execNodes, + isAdmin: this.place.isAdmin(), + }), + projectQuery: this.browser.projectQuery, projectSearchAvailable: canCallGatewayMethod( this.context?.gateway.snapshot, "projects.searchRemote", @@ -2282,183 +362,138 @@ class NewSessionPage extends OpenClawLightDomElement { "projects.add", "operator.write", ), - remoteProjects: this.projectSearchResult?.projects ?? [], - projectSearchCredential: this.projectSearchResult?.credential ?? null, - projectSearchLoading: this.projectSearchLoading, - projectSearchError: this.projectSearchError, - projectCloneBusy: this.projectCloneBusy, - projectCloneError: this.projectCloneError, - projectId: this.projectId, - sessions: this.context?.sessions.state.result?.sessions ?? [], - execNodes: this.isAdmin() ? execNodes : [], - gatewayName: this.gatewayName, - cloudProfiles: this.isAdmin() ? cloudProfiles : [], - cloudProfileId: this.cloudProfileId, - execNode: this.execNode, - syncFolder: this.folder.trim() || this.workspacePath(), - worktree: this.worktree, - worktreeVisible: this.worktreeAvailable() || Boolean(this.cloudProfileId) || this.worktree, - worktreeAvailable: this.worktreeAvailable(), + remoteProjects: this.browser.projectSearchResult?.projects ?? [], + projectSearchCredential: this.browser.projectSearchResult?.credential ?? null, + projectSearchLoading: this.browser.projectSearchLoading, + projectSearchError: this.browser.projectSearchError, + projectCloneBusy: this.browser.projectCloneBusy, + projectCloneError: this.browser.projectCloneError, + projectId: this.place.projectId, + execNodes: this.place.isAdmin() ? execNodes : [], + gatewayName: this.gateway.gatewayName, + cloudProfiles: this.place.isAdmin() ? cloudProfiles : [], + cloudProfileId: this.place.cloudProfileId, + execNode: this.place.execNode, + syncFolder: this.place.folder.trim() || this.place.workspacePath(), + worktree: this.place.worktree, + worktreeVisible: + this.place.worktreeAvailable() || Boolean(this.place.cloudProfileId) || this.place.worktree, + worktreeAvailable: this.place.worktreeAvailable(), worktreeDisabledReason: - this.repository.kind === "checking" + this.place.repository.kind === "checking" ? t("newSession.checkingGit") - : this.repository.kind === "unavailable" + : this.place.repository.kind === "unavailable" ? t("newSession.gitCheckUnavailable") : undefined, - cloudDisabledReason, + cloudDisabledReason: this.submission.cloudDisabledReason(), branches, - branchesLoading: this.repository.kind === "checking", - baseRef: this.baseRef, - worktreeName: this.worktreeName, - submitting: this.submitting || this.projectCloneBusy, - pendingCloud: Boolean(this.pendingCloud.sessionKey), - // Admin gates only the discovered choices. An existing node or cloud - // selection always keeps the destination axis visible — hiding it (e.g. - // after a failed node.list or an auth downgrade) would misreport a - // remote-targeted draft as Gateway-local. + branchesLoading: this.place.repository.kind === "checking", + baseRef: this.place.baseRef, + worktreeName: this.place.worktreeName, + submitting: this.submission.submitting || this.browser.projectCloneBusy, + pendingCloud: Boolean(this.submission.pendingCloud.sessionKey), showDestinations: - Boolean(this.execNode) || - Boolean(this.cloudProfileId) || - (this.isAdmin() && (execNodes.length > 0 || cloudProfiles.length > 0)), - popoverOpen: this.placePopoverOpen, - popoverHiding: this.placePopoverHiding, - browserTarget: this.browserTarget, - browserListing: this.browserListing, - browserLoading: this.browserLoading, - browserError: this.browserError, - browserPathDraft: this.browserPathDraft, - usableBrowserPath: this.usableBrowserPath(), - registerProjectPath: this.browserProjectPath, - registeringProject: this.browserRegistering, - onGuardTransition: (event) => this.guardPopoverTransition(event, this.placePopoverHiding), - onPopoverShow: () => { - this.placePopoverOpen = true; - this.showBrowserRoot(); - }, - onPopoverHide: () => { - this.placePopoverOpen = false; - this.placePopoverHiding = true; - this.showBrowserRoot(); - }, - onPopoverAfterHide: () => { - this.placePopoverHiding = false; - this.restorePopoverTrigger("new-session-place-trigger", ".new-session-page__place-popover"); - }, - onSelectExecNode: (nodeId) => this.selectExecNode(nodeId), - onSelectCloudProfile: (profileId) => this.selectCloudProfile(profileId), - onSelectProject: (projectId) => this.selectProjectId(projectId), - onProjectQueryInput: (query) => this.changeProjectQuery(query), - onCloneProject: (gitUrl) => void this.addRemoteProject(gitUrl), + Boolean(this.place.execNode) || + Boolean(this.place.cloudProfileId) || + (this.place.isAdmin() && (execNodes.length > 0 || cloudProfiles.length > 0)), + popoverOpen: this.browser.placePopoverOpen, + popoverHiding: this.browser.placePopoverHiding, + browserTarget: this.browser.browserTarget, + browserListing: this.browser.browserListing, + browserLoading: this.browser.browserLoading, + browserError: this.browser.browserError, + browserPathDraft: this.browser.browserPathDraft, + usableBrowserPath: this.browser.usableBrowserPath(), + registerProjectPath: this.browser.browserProjectPath, + registeringProject: this.browser.browserRegistering, + onGuardTransition: (event) => this.browser.guardPopoverTransition(event), + onPopoverShow: () => this.browser.onPopoverShow(), + onPopoverHide: () => this.browser.onPopoverHide(), + onPopoverAfterHide: () => this.browser.onPopoverAfterHide(), + onSelectExecNode: (nodeId) => this.place.selectExecNode(nodeId), + onSelectCloudProfile: (profileId) => this.place.selectCloudProfile(profileId), + onSelectProject: (projectId) => this.place.selectProjectId(projectId), + onProjectQueryInput: (query) => this.browser.changeProjectQuery(query), + onCloneProject: (gitUrl) => void this.browser.addRemoteProject(gitUrl), onApplyFolder: (folder, execNode) => - this.applyFolder(folder, execNode, !execNode && this.browserListing?.path === folder), - onBrowse: (target) => this.selectBrowserTarget(target), + this.place.applyFolder( + folder, + execNode, + !execNode && this.browser.browserListing?.path === folder, + ), + onBrowse: (target) => this.browser.selectBrowserTarget(target), onBrowserPathDraftChange: (value) => { - this.browserPathDraft = value; - }, - onBrowserNavigate: (path) => this.loadBrowser(path), - onBrowserBack: () => this.showBrowserRoot(), - onRegisterProject: (path) => void this.registerBrowserProject(path), - onClose: () => this.closeBrowser(), - onToggleWorktree: () => { - if (this.cloudProfileId) { - return; - } - this.worktree = !this.worktree; - this.preferredWorktreeRestore = false; - this.worktreeSelectedByUser = true; - this.persistPreference({ - folder: this.folder.trim() || this.workspacePath(), - worktree: this.worktree, - }); - if (this.worktree && this.repository.kind !== "git") { - this.maybeLoadBranches(); - } - }, - onBaseRefInput: (baseRef) => { - if (!this.submitting) { - this.baseRefEditGeneration += 1; - this.baseRef = baseRef; - } - }, - onWorktreeNameInput: (worktreeName) => { - if (!this.submitting) { - this.worktreeName = worktreeName; - } + this.browser.browserPathDraft = value; }, + onBrowserNavigate: (path) => this.browser.loadBrowser(path), + onBrowserBack: () => this.browser.showRoot(), + onRegisterProject: (path) => void this.browser.registerBrowserProject(path), + onClose: () => this.browser.close(), + onToggleWorktree: () => this.place.toggleWorktree(), + onBaseRefInput: (baseRef) => this.place.setBaseRef(baseRef), + onWorktreeNameInput: (worktreeName) => this.place.setWorktreeName(worktreeName), }); } - private renderTargetBar() { - const agents = this.agents(); - return catalog.renderBar({ - data: this.data, - agentSelect: agents.length > 1 ? this.renderAgentSelect(agents) : nothing, - placeSelect: this.renderPlaceSelect(), - retrying: this.catalogRetrying, - onRetry: this.handleCatalogRetry, - }); - } - - /** Target row + composer, rendered mid-screen between the hero and recents. */ private renderDraftBlock() { - const worktreeNameInvalid = this.worktree && !isWorktreeNameValid(this.worktreeName); + const worktreeNameInvalid = + this.place.worktree && !isWorktreeNameValid(this.place.worktreeName); return html` -
+
${this.renderTargetBar()} ${worktreeNameInvalid ? renderDraftError(t("newSession.worktreeNameInvalid")) : nothing} - ${this.error ? renderDraftError(this.error) : nothing} - ${this.submissionOutcomeUnknown + ${this.submission.error ? renderDraftError(this.submission.error) : nothing} + ${this.submission.submissionOutcomeUnknown ? renderDraftError( t( - this.submissionOutcomeUnknown === "gateway-changed" + this.submission.submissionOutcomeUnknown === "gateway-changed" ? "newSession.createOutcomeUnknown" : "newSession.cloudSetupInterrupted", ), ) : nothing} ${renderNewSessionDraftComposer({ - agent: this.selectedAgent(), - agentId: this.agentId, - attachmentDraft: this.attachmentDraft, - canSubmit: this.canSubmit(), - submitDisabledReason: this.submitDisabledReason(), + agent: this.place.selectedAgent(), + agentId: this.place.agentId, + attachmentDraft: this.submission.attachmentDraft, + canSubmit: this.submission.canSubmit(), + submitDisabledReason: this.submission.submitDisabledReason(), context: this.context, isCatalogTarget: catalog.isTarget(this.data), - message: this.message, - visibility: this.visibility, - draftAvailable: this.canStartAsDraft(), - modelControl: this.modelControl, + message: this.submission.message, + visibility: this.submission.visibility, + draftAvailable: this.submission.canStartAsDraft(), + modelControl: this.place.modelControl, requiresModifier: loadSettings().chatSendShortcut === "modifier-enter", - submitting: this.submitting, - textareaController: this.composerTextarea, - messageLocked: Boolean(this.pendingCloud.sessionKey), - incognitoDisabledReason: this.incognitoDisabledReason(), - terminalAction: this.showStartInTerminal() + submitting: this.submission.submitting, + textareaController: this.submission.composerTextarea, + messageLocked: Boolean(this.submission.pendingCloud.sessionKey), + incognitoDisabledReason: this.submission.incognitoDisabledReason(), + terminalAction: this.submission.showStartInTerminal() ? { - canStart: this.canSubmit("terminal"), - disabledReason: this.terminalStartDisabledReason(), - onStart: () => void this.startInTerminal(), + canStart: this.submission.canSubmit("terminal"), + disabledReason: this.submission.terminalStartDisabledReason(), + onStart: () => void this.submission.startInTerminal(), } : undefined, onInput: (message) => { - if (!this.submitting && !this.pendingCloud.sessionKey) { + if (!this.submission.submitting && !this.submission.pendingCloud.sessionKey) { this.setMessageFromUser(message); } }, onVisibilityChange: (visibility) => { - if (!this.submitting && !this.pendingCloud.sessionKey) { - this.visibility = visibility; + if (!this.submission.submitting && !this.submission.pendingCloud.sessionKey) { + this.submission.setVisibility(visibility); } }, - onSubmit: () => void this.submit(), + onSubmit: () => void this.submission.submit(), })}
`; } - /** Same welcome block as the empty-chat start screen, keyed to the draft's agent. */ private renderWelcome() { - const agent = this.selectedAgent(); + const agent = this.place.selectedAgent(); const identity = agent?.identity; const gateway = this.context?.gateway.snapshot; return renderWelcomeState({ @@ -2467,11 +502,11 @@ class NewSessionPage extends OpenClawLightDomElement { assistantAvatarUrl: identity?.avatarUrl ?? null, hint: t("newSession.hint"), composer: this.renderDraftBlock(), - modelSetupRequired: this.requiresModelSetup(), + modelSetupRequired: this.submission.requiresModelSetup(), onModelSetup: () => this.context?.navigate("model-setup"), sessions: this.context?.sessions.state.result, sessionKey: buildAgentMainSessionKey({ - agentId: this.agentId || "main", + agentId: this.place.agentId || "main", mainKey: this.context?.agents.state.agentsList?.mainKey, }), sessionHost: { @@ -2480,13 +515,13 @@ class NewSessionPage extends OpenClawLightDomElement { hello: gateway?.hello ?? null, }, onDraftChange: (next) => { - if (!this.submitting && !this.pendingCloud.sessionKey) { + if (!this.submission.submitting && !this.submission.pendingCloud.sessionKey) { this.setMessageFromUser(next); } }, - onSend: () => void this.submit(), + onSend: () => void this.submission.submit(), onOpenSession: (sessionKey) => { - if (this.submitting || this.pendingCloud.sessionKey) { + if (this.submission.submitting || this.submission.pendingCloud.sessionKey) { return; } const context = this.context; @@ -2497,15 +532,11 @@ class NewSessionPage extends OpenClawLightDomElement { selection: context.agentSelection, gateway: context.gateway, sessionKey, - agentId: this.agentId, + agentId: this.place.agentId, }); context.navigate( "chat", - sessionNavigationTarget({ - context, - face: "chat", - sessionKey, - }).options, + sessionNavigationTarget({ context, face: "chat", sessionKey }).options, ); }, }); @@ -2516,8 +547,8 @@ class NewSessionPage extends OpenClawLightDomElement {
${this.renderWelcome()} @@ -2530,6 +561,3 @@ class NewSessionPage extends OpenClawLightDomElement { if (!customElements.get("openclaw-new-session-page")) { customElements.define("openclaw-new-session-page", NewSessionPage); } - -export type { NewSessionPage }; -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/ui/src/pages/new-session/place-picker.test.ts b/ui/src/pages/new-session/place-picker.test.ts index c9444f73324b..f5f88d5b1ca9 100644 --- a/ui/src/pages/new-session/place-picker.test.ts +++ b/ui/src/pages/new-session/place-picker.test.ts @@ -11,8 +11,8 @@ function placeParams(overrides: Partial = {}): PlaceSelectPar canWrite: true, folder: "/workspace", workspace: "/workspace", - workspaceRoots: ["/workspace"], projects: [], + recents: [], projectQuery: "", projectSearchAvailable: true, projectAddAvailable: true, @@ -23,7 +23,6 @@ function placeParams(overrides: Partial = {}): PlaceSelectPar projectCloneBusy: false, projectCloneError: null, projectId: "", - sessions: [], execNodes: [], gatewayName: "", cloudProfiles: [], diff --git a/ui/src/pages/new-session/place-picker.ts b/ui/src/pages/new-session/place-picker.ts index 7c581bc29799..7afe7c47cc5c 100644 --- a/ui/src/pages/new-session/place-picker.ts +++ b/ui/src/pages/new-session/place-picker.ts @@ -9,9 +9,8 @@ import { icons } from "../../components/icons.ts"; import { t } from "../../i18n/index.ts"; import { renderCloudProfileMenuItems, renderSessionMenuItem } from "./cloud-target.ts"; import type { BrowserTarget, DraftBranches, DraftCloudProfile, DraftNode } from "./discovery.ts"; -import { folderDisplayName, isKnownWorkspacePath } from "./path.ts"; +import { folderDisplayName } from "./path.ts"; import { disambiguate, isPhoneFamily, nodeTooltip } from "./place-labels.ts"; -import { recentPlaces, type RecentPlaceSource } from "./recent-places.ts"; function parentFolderDisplayName(path: string): string | undefined { const trimmed = path.replace(/[\\/]+$/u, ""); @@ -165,9 +164,8 @@ export function renderPlaceSelect(params: { canWrite: boolean; folder: string; workspace: string; - workspaceRoots: readonly string[]; projects: readonly ProjectRecord[]; - recents?: readonly ProjectRecent[]; + recents: readonly ProjectRecent[]; projectQuery: string; projectSearchAvailable: boolean; projectAddAvailable: boolean; @@ -178,10 +176,9 @@ export function renderPlaceSelect(params: { projectCloneBusy: boolean; projectCloneError: string | null; projectId: string; - sessions: readonly RecentPlaceSource[]; execNodes: DraftNode[]; gatewayName: string; - cloudProfiles: DraftCloudProfile[]; + cloudProfiles: readonly DraftCloudProfile[]; cloudProfileId: string; execNode: string; syncFolder: string; @@ -261,33 +258,7 @@ export function renderPlaceSelect(params: { : gatewayLabel; const label = params.showDestinations ? `${folderLabel} · ${destinationLabel}` : folderLabel; const effectiveFolder = folder || params.workspace; - const allowGatewayFolder = (recentFolder: string) => - params.isAdmin || isKnownWorkspacePath(params.workspaceRoots, recentFolder); - const serverRecents = params.recents?.filter((recent) => - recent.kind === "project" - ? params.projects.some((project) => project.id === recent.projectId) - : recent.execNode - ? params.execNodes.some((node) => node.nodeId === recent.execNode) - : allowGatewayFolder(recent.folder), - ); - const recents: ProjectRecent[] = - serverRecents ?? - recentPlaces(params.sessions, { - workspace: params.workspace, - execNodes: params.execNodes, - allowGatewayFolder, - }).map((recent) => { - const item: ProjectRecent = { - kind: "folder", - folder: recent.folder, - displayName: folderDisplayName(recent.folder), - }; - if (recent.execNode) { - item.execNode = recent.execNode; - } - return item; - }); - const recentItems = recents.map((recent) => { + const recentItems = params.recents.map((recent) => { const node = recent.kind === "folder" && recent.execNode ? params.execNodes.find((candidate) => candidate.nodeId === recent.execNode) @@ -498,7 +469,7 @@ export function renderPlaceSelect(params: { ${t("newSession.projectsAdminHint")}
` : nothing} - ${recents.length > 0 + ${params.recents.length > 0 ? html`
${t("newSession.recentFolders")}
${recentItems.map((recent, index) => { From f6fff4f7fdb6f25e24c73ec22aa363eb4a8fabf3 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:18:34 -0700 Subject: [PATCH 007/165] refactor: canonicalize aliases and classify test suites (#122407) * refactor: use canonical re-export names * fix(test): classify suite support as test source * fix(agents): retarget gateway stub session-entry import * test(gateway): retarget session-utils mock keys after alias removal --- .oxlintrc.json | 25 +++++++------------ scripts/lib/changed-path-facts.mjs | 4 +-- scripts/lib/ci-changed-node-test-plan.mts | 7 +++++- scripts/test-projects.test-support.mts | 4 +-- .../tools/embedded-gateway-stub.runtime.ts | 2 +- src/gateway/control-ui-session-prs.ts | 11 +++++--- src/gateway/managed-image-attachments.test.ts | 2 +- src/gateway/managed-image-attachments.ts | 6 ++--- src/gateway/mcp-app-reconstruction.test.ts | 2 +- src/gateway/mcp-app-reconstruction.ts | 4 +-- src/gateway/server-chat.agent-events.test.ts | 2 +- src/gateway/server-chat.ts | 6 ++--- .../__mocks__/tools-effective.runtime.ts | 2 +- src/gateway/server-methods/artifacts.test.ts | 2 +- src/gateway/server-methods/artifacts.ts | 6 ++--- .../server-methods/chat-history-handler.ts | 4 +-- .../chat-message-get-handler.ts | 7 ++++-- .../chat.directive-tags.test.ts | 2 +- src/gateway/server-methods/chat.ts | 4 +-- src/gateway/server-methods/cron.ts | 6 ++--- .../server-methods/cron.validation.test.ts | 2 +- .../deleted-agent-guard.test-helpers.ts | 6 ++--- src/gateway/server-methods/sessions-create.ts | 7 ++++-- .../server-methods/sessions-diff.test.ts | 2 +- src/gateway/server-methods/sessions-diff.ts | 11 +++++--- .../server-methods/sessions-files.test.ts | 2 +- .../sessions-files.touched-files.test.ts | 2 +- src/gateway/server-methods/sessions-files.ts | 4 +-- .../server-methods/sessions-messaging.ts | 4 +-- .../sessions.abort-agent-scope.test.ts | 2 +- ...sions.messages-subscribe-approvals.test.ts | 2 +- .../sessions.send-followup-status.test.ts | 7 +++--- .../server-methods/task-suggestions.test.ts | 6 +++-- .../server-methods/task-suggestions.ts | 8 +++--- .../server-methods/tools-effective.runtime.ts | 2 +- .../server-methods/tools-effective.test.ts | 2 +- src/gateway/server-methods/tools-effective.ts | 4 +-- .../usage.sessions-usage.test.ts | 6 ++--- src/gateway/server-methods/usage.ts | 4 +-- src/gateway/server-session-events.test.ts | 2 +- src/gateway/server-session-events.ts | 6 ++--- src/gateway/session-companion-context.ts | 6 ++--- src/gateway/session-create-service.ts | 13 ++++++---- src/gateway/session-utils.test.ts | 16 ++++++------ src/gateway/session-utils.ts | 2 +- .../worker-session-tool-executor.test.ts | 2 +- .../worker-session-tool-executor.ts | 12 ++++++--- .../worker-session-tool-topology.ts | 14 ++++++----- src/infra/json-files.ts | 10 ++++---- src/infra/openclaw-root.fs.runtime.ts | 4 +-- src/infra/secret-file.ts | 2 +- ...ate-migrations.workspace-setup-receipts.ts | 2 +- src/infra/state-migrations.workspace-setup.ts | 8 +++--- src/media-generation/model-ref.ts | 6 ++--- src/plugin-sdk/command-status.runtime.test.ts | 2 +- src/plugin-sdk/command-status.runtime.ts | 4 +-- src/transcripts/provider-registry.ts | 2 +- src/tui/embedded-backend.test.ts | 2 +- src/tui/embedded-backend.ts | 6 ++--- .../gateway-usage-memory-apis.e2e.test.ts | 4 +-- test/scripts/changed-path-facts.test.ts | 6 +++++ .../scripts/ci-changed-node-test-plan.test.ts | 3 +++ test/scripts/oxlint-config.test.ts | 15 +++++++++-- 63 files changed, 191 insertions(+), 149 deletions(-) diff --git a/.oxlintrc.json b/.oxlintrc.json index c12ce2b5494e..7ccf77f27224 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -262,8 +262,8 @@ }, { "files": [ - "**/*.test.ts", - "**/*.test.tsx", + "**/*.{test,suite}.ts", + "**/*.{test,suite}.tsx", "**/*.e2e.test.ts", "**/*.live.test.ts", "**/*test-harness.ts", @@ -282,8 +282,7 @@ "extensions/**/*.{js,ts,mts,cts}" ], "excludeFiles": [ - "**/*.test.*", - "**/*.spec.*", + "**/*.{test,spec,suite}.*", "**/__generated__/**", "**/generated/**", "**/protocol-gen/**", @@ -304,8 +303,7 @@ "extensions/**/*.{jsx,tsx}" ], "excludeFiles": [ - "**/*.test.*", - "**/*.spec.*", + "**/*.{test,spec,suite}.*", "**/__generated__/**", "**/generated/**", "**/protocol-gen/**", @@ -326,8 +324,7 @@ "extensions/**/*.{mjs,cjs}" ], "excludeFiles": [ - "**/*.test.*", - "**/*.spec.*", + "**/*.{test,spec,suite}.*", "**/__generated__/**", "**/generated/**", "**/protocol-gen/**", @@ -342,14 +339,10 @@ }, { "files": [ - "src/**/*.test.*", - "src/**/*.spec.*", - "ui/src/**/*.test.*", - "ui/src/**/*.spec.*", - "packages/**/*.test.*", - "packages/**/*.spec.*", - "extensions/**/*.test.*", - "extensions/**/*.spec.*" + "src/**/*.{test,spec,suite}.*", + "ui/src/**/*.{test,spec,suite}.*", + "packages/**/*.{test,spec,suite}.*", + "extensions/**/*.{test,spec,suite}.*" ], "excludeFiles": [ "**/__generated__/**", diff --git a/scripts/lib/changed-path-facts.mjs b/scripts/lib/changed-path-facts.mjs index ea2d9d93461c..8de19e28f80b 100644 --- a/scripts/lib/changed-path-facts.mjs +++ b/scripts/lib/changed-path-facts.mjs @@ -23,9 +23,9 @@ const SURFACE_PATTERNS = [ ["legacyRootAsset", /^assets\//u], ]; const CHANGED_LANE_TEST_PATH_RE = - /(?:^|\/)(?:test|__tests__)\/|(?:\.|\/)(?:test|spec|e2e|browser\.test)\.[cm]?[jt]sx?$|(?:^|\/)[^/]+\.test-(?:helpers|support)\.[cm]?[jt]sx?$/u; + /(?:^|\/)(?:test|__tests__)\/|(?:\.|\/)(?:test|spec|suite|e2e|browser\.test)\.[cm]?[jt]sx?$|(?:^|\/)[^/]+\.test-(?:helpers|support)\.[cm]?[jt]sx?$/u; const TEST_ONLY_PATH_RE = - /(^test\/|\/test\/|\/tests\/|(?:^|\/)[^/]+\.(?:test|spec|test-utils|test-(?:helpers|support|harness)|e2e-harness)\.[cm]?[jt]sx?$)/u; + /(^test\/|\/test\/|\/tests\/|(?:^|\/)[^/]+\.(?:test|spec|suite|test-utils|test-(?:helpers|support|harness)|e2e-harness)\.[cm]?[jt]sx?$)/u; const NATIVE_ONLY_PATH_RE = /^(?:apps\/android\/|apps\/ios\/|apps\/macos\/|apps\/macos-mlx-tts\/|apps\/shared\/|apps\/swabble\/|Swabble\/|appcast\.xml$)/u; diff --git a/scripts/lib/ci-changed-node-test-plan.mts b/scripts/lib/ci-changed-node-test-plan.mts index 89860e30d00f..a40c74b5d6c2 100644 --- a/scripts/lib/ci-changed-node-test-plan.mts +++ b/scripts/lib/ci-changed-node-test-plan.mts @@ -6,6 +6,7 @@ import { findUnmatchedExplicitTestTargets, hasImportGraphImpactOnTargets, isTestFileTarget, + isTestSupportFileTarget, resolveChangedTestTargetPlan, } from "../test-projects.test-support.mts"; import { @@ -53,7 +54,11 @@ const splitNodeTestConfigs = new Set( ); function isTestOnlyPath(changedPath: string) { - return isTestFileTarget(changedPath) || changedPath.startsWith("test/"); + return ( + isTestFileTarget(changedPath) || + isTestSupportFileTarget(changedPath) || + changedPath.startsWith("test/") + ); } // Inputs `build:ci-artifacts` consumes: runtime/plugin/package sources plus diff --git a/scripts/test-projects.test-support.mts b/scripts/test-projects.test-support.mts index 725ee3ddf743..ce4ee8db2914 100644 --- a/scripts/test-projects.test-support.mts +++ b/scripts/test-projects.test-support.mts @@ -1000,12 +1000,12 @@ export function isTestFileTarget(arg: string) { return /\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(arg); } -function isTestSupportFileTarget(arg: string) { +export function isTestSupportFileTarget(arg: string) { if (/(?:^|\/)(?:test-helpers|test-support)(?:\/|$)/u.test(arg)) { return true; } const basename = path.posix.basename(arg).replace(/\.[cm]?[jt]sx?$/u, ""); - return /(?:^|[._-])test-(?:helpers|support)(?:[._-]|$)/u.test(basename); + return /(?:^|[._-])(?:suite|test-(?:helpers|support))(?:[._-]|$)/u.test(basename); } function isLikelyFileTarget(arg: string) { diff --git a/src/agents/tools/embedded-gateway-stub.runtime.ts b/src/agents/tools/embedded-gateway-stub.runtime.ts index b7db33621c11..6add2d7168c0 100644 --- a/src/agents/tools/embedded-gateway-stub.runtime.ts +++ b/src/agents/tools/embedded-gateway-stub.runtime.ts @@ -34,7 +34,7 @@ export { export { listSessionsFromStoreAsync, loadCombinedSessionStoreForGatewayCore, - loadSessionEntryReadOnly as loadSessionEntry, + loadGatewaySessionEntryReadOnly as loadSessionEntry, resolveSessionModelRef, } from "../../gateway/session-utils.js"; export { resolveSessionKeyFromResolveParams } from "../../gateway/sessions-resolve.js"; diff --git a/src/gateway/control-ui-session-prs.ts b/src/gateway/control-ui-session-prs.ts index b081fdfaad36..e40a3aeeb665 100644 --- a/src/gateway/control-ui-session-prs.ts +++ b/src/gateway/control-ui-session-prs.ts @@ -32,7 +32,7 @@ import { type SessionPullRequestGitContext, type SessionPullRequestLocalGitDeps, } from "./control-ui-session-prs-local-git.js"; -import { loadSessionEntryReadOnly } from "./session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "./session-utils.js"; const SUCCESS_CACHE_MS = 60_000; // Back off refetches while GitHub reports quota exhaustion; the UI keeps @@ -94,9 +94,12 @@ type LoadSessionPullRequestDeps = SessionPullRequestLocalGitDeps & { function resolveSessionPullRequestGitRoot( params: ControlUiSessionPullRequestsParams, ): string | null { - const { cfg, entry, storePath, canonicalKey } = loadSessionEntryReadOnly(params.sessionKey, { - agentId: params.agentId, - }); + const { cfg, entry, storePath, canonicalKey } = loadGatewaySessionEntryReadOnly( + params.sessionKey, + { + agentId: params.agentId, + }, + ); // Same session/agent scoping as sessions.files.*: a missing entry means an // unknown or deleted session, which must not fall back to some agent // workspace and surface another checkout's PRs. diff --git a/src/gateway/managed-image-attachments.test.ts b/src/gateway/managed-image-attachments.test.ts index 575048781728..89b9398fdf55 100644 --- a/src/gateway/managed-image-attachments.test.ts +++ b/src/gateway/managed-image-attachments.test.ts @@ -67,7 +67,7 @@ vi.mock("./http-utils.js", () => ({ vi.mock("./session-utils.js", () => ({ loadSessionEntry: loadSessionEntryMock, - loadSessionEntryReadOnly: loadSessionEntryMock, + loadGatewaySessionEntryReadOnly: loadSessionEntryMock, resolveSessionHistoryTranscriptPathAsync: resolveSessionHistoryTranscriptPathMock, })); diff --git a/src/gateway/managed-image-attachments.ts b/src/gateway/managed-image-attachments.ts index 512bc66e7f3e..d9867739f245 100644 --- a/src/gateway/managed-image-attachments.ts +++ b/src/gateway/managed-image-attachments.ts @@ -68,7 +68,7 @@ import { import { authorizeOperatorScopesForMethod } from "./method-scopes.js"; import { readSessionMessagesWithSourceAsync } from "./session-transcript-readers.js"; import { - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, resolveSessionHistoryTranscriptPathAsync, } from "./session-utils.js"; @@ -974,7 +974,7 @@ async function getSessionManagedOutgoingAttachmentIndex( } const usesRuntimeState = !stateDir || path.resolve(stateDir) === path.resolve(resolveStateDir()); const env = stateDir ? { ...process.env, OPENCLAW_STATE_DIR: stateDir } : process.env; - type SessionEntry = ReturnType["entry"]; + type SessionEntry = ReturnType["entry"]; let matched: { entry: NonNullable; storePath: string } | undefined; for (const target of discovery.targets) { const exact = loadExactSessionEntryReadOnlyResult({ @@ -1014,7 +1014,7 @@ async function getSessionManagedOutgoingAttachmentIndex( let entry: SessionEntry = matched?.entry; let storePath = matched?.storePath ?? discovery.targets[0]?.storePath ?? ""; if (!entry && usesRuntimeState) { - const loaded = loadSessionEntryReadOnly(sessionKey, { agentId: ownerAgentId }); + const loaded = loadGatewaySessionEntryReadOnly(sessionKey, { agentId: ownerAgentId }); const exact = loadExactSessionEntryReadOnlyResult({ agentId: ownerAgentId, clone: false, diff --git a/src/gateway/mcp-app-reconstruction.test.ts b/src/gateway/mcp-app-reconstruction.test.ts index 052397677f2c..68404f6b5fa2 100644 --- a/src/gateway/mcp-app-reconstruction.test.ts +++ b/src/gateway/mcp-app-reconstruction.test.ts @@ -30,7 +30,7 @@ vi.mock("./session-transcript-readers.js", () => ({ })); vi.mock("./session-utils.js", () => ({ loadSessionEntry: mocks.loadSessionEntry, - loadSessionEntryReadOnly: mocks.loadSessionEntry, + loadGatewaySessionEntryReadOnly: mocks.loadSessionEntry, })); import { mintMcpAppViewFromTranscript, restoreMcpAppView } from "./mcp-app-reconstruction.js"; diff --git a/src/gateway/mcp-app-reconstruction.ts b/src/gateway/mcp-app-reconstruction.ts index 911e16103d30..32354eecf27c 100644 --- a/src/gateway/mcp-app-reconstruction.ts +++ b/src/gateway/mcp-app-reconstruction.ts @@ -14,7 +14,7 @@ import type { OpenClawConfig } from "../config/types.openclaw.js"; import { resolveAgentIdFromSessionKey } from "../routing/session-key.js"; import { getOrCreatePromise } from "../shared/lazy-promise.js"; import { visitSessionMessagesAsync } from "./session-transcript-readers.js"; -import { loadSessionEntryReadOnly } from "./session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "./session-utils.js"; const MCP_APP_RESTORE_IN_FLIGHT_KEY = Symbol.for("openclaw.mcpAppRestoreInFlight"); @@ -252,7 +252,7 @@ async function reconstructMcpAppView(params: { viewId?: string; }): Promise { const agentId = resolveAgentIdFromSessionKey(params.sessionKey); - const loaded = loadSessionEntryReadOnly(params.sessionKey, { agentId }); + const loaded = loadGatewaySessionEntryReadOnly(params.sessionKey, { agentId }); const sessionId = loaded.entry?.sessionId; if (!sessionId) { return undefined; diff --git a/src/gateway/server-chat.agent-events.test.ts b/src/gateway/server-chat.agent-events.test.ts index 217281b9379f..d40b3d9dbfe4 100644 --- a/src/gateway/server-chat.agent-events.test.ts +++ b/src/gateway/server-chat.agent-events.test.ts @@ -75,7 +75,7 @@ vi.mock("./session-utils.js", () => { })); return { loadSessionEntry, - loadSessionEntryReadOnly: loadSessionEntry, + loadGatewaySessionEntryReadOnly: loadSessionEntry, }; }); diff --git a/src/gateway/server-chat.ts b/src/gateway/server-chat.ts index 086b5b7e262f..f08c548d760e 100644 --- a/src/gateway/server-chat.ts +++ b/src/gateway/server-chat.ts @@ -65,7 +65,7 @@ import { resolveSessionSubscriptionKey, resolveSessionSubscriptionKeys, } from "./session-subscription-keys.js"; -import { loadSessionEntryReadOnly } from "./session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "./session-utils.js"; import { formatForLog } from "./ws-log.js"; export { @@ -522,7 +522,7 @@ export function createAgentEventHandler({ event: AgentEventPayload, ): { suppress: boolean } => { try { - const { entry } = loadSessionEntryReadOnly(sessionKey, { + const { entry } = loadGatewaySessionEntryReadOnly(sessionKey, { ...(agentId ? { agentId } : {}), clone: false, }); @@ -1341,7 +1341,7 @@ export function createAgentEventHandler({ return runVerbose ?? "off"; } try { - const { cfg, entry } = loadSessionEntryReadOnly(sessionKey); + const { cfg, entry } = loadGatewaySessionEntryReadOnly(sessionKey); const sessionVerbose = normalizeVerboseLevel(entry?.verboseLevel); const sessionUpdatedAt = typeof entry?.updatedAt === "number" ? entry.updatedAt : undefined; const sessionChangedAfterRunStarted = diff --git a/src/gateway/server-methods/__mocks__/tools-effective.runtime.ts b/src/gateway/server-methods/__mocks__/tools-effective.runtime.ts index 57331d9d9dee..2c33a8da63bf 100644 --- a/src/gateway/server-methods/__mocks__/tools-effective.runtime.ts +++ b/src/gateway/server-methods/__mocks__/tools-effective.runtime.ts @@ -10,7 +10,7 @@ export { getRegisteredAgentHarness } from "../../../agents/harness/registry.js"; export { resolveReplyToMode } from "../../../auto-reply/reply/reply-threading.js"; export { resolveRuntimeConfigCacheKey } from "../../../config/config.js"; export { deliveryContextFromSession } from "../../../utils/delivery-context.shared.js"; -export { loadSessionEntryReadOnly, resolveSessionModelRef } from "../../session-utils.js"; +export { loadGatewaySessionEntryReadOnly, resolveSessionModelRef } from "../../session-utils.js"; export const toolsEffectiveGlobalAgentRuntimeMocks = { resolveEffectiveToolInventory: vi.fn( diff --git a/src/gateway/server-methods/artifacts.test.ts b/src/gateway/server-methods/artifacts.test.ts index c5ae97682602..dd9bb3f10326 100644 --- a/src/gateway/server-methods/artifacts.test.ts +++ b/src/gateway/server-methods/artifacts.test.ts @@ -22,7 +22,7 @@ vi.mock("../session-utils.js", async () => { return { ...actual, loadSessionEntry: hoisted.loadSessionEntry, - loadSessionEntryReadOnly: hoisted.loadSessionEntry, + loadGatewaySessionEntryReadOnly: hoisted.loadSessionEntry, }; }); diff --git a/src/gateway/server-methods/artifacts.ts b/src/gateway/server-methods/artifacts.ts index 23b2bb69bca4..c5cbe2289674 100644 --- a/src/gateway/server-methods/artifacts.ts +++ b/src/gateway/server-methods/artifacts.ts @@ -34,7 +34,7 @@ import { resolveStoredSessionKeyForAgentStore, } from "../session-store-key.js"; import { visitSessionMessagesAsync } from "../session-transcript-readers.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import type { GatewayRequestHandlers, RespondFn } from "./types.js"; import { assertValidParams } from "./validation.js"; @@ -526,8 +526,8 @@ async function loadArtifacts( const scopedGlobalAgentId = cfg?.session?.scope === "global" && sessionKey === "global" ? resolved.agentId : undefined; const { storePath, entry } = scopedGlobalAgentId - ? loadSessionEntryReadOnly(sessionKey, { agentId: scopedGlobalAgentId }) - : loadSessionEntryReadOnly(sessionKey); + ? loadGatewaySessionEntryReadOnly(sessionKey, { agentId: scopedGlobalAgentId }) + : loadGatewaySessionEntryReadOnly(sessionKey); const sessionId = entry?.sessionId; if (!sessionId || !storePath) { return { sessionKey, artifacts: [] }; diff --git a/src/gateway/server-methods/chat-history-handler.ts b/src/gateway/server-methods/chat-history-handler.ts index 9c8f8b0e6b50..5cc24869489d 100644 --- a/src/gateway/server-methods/chat-history-handler.ts +++ b/src/gateway/server-methods/chat-history-handler.ts @@ -36,7 +36,7 @@ import { capArrayByJsonBytes } from "../session-transcript-readers.js"; import { buildGatewaySessionInfo, getSessionDefaults, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, listAgentsForGateway, resolveSessionModelRef, resolveSessionStoreKey, @@ -203,7 +203,7 @@ async function handleChatHistoryRequest({ const { cfg, storePath, store, entry, canonicalKey } = measureDiagnosticsTimelineSpanSync( `gateway.${method}.session_entry`, () => - loadSessionEntryReadOnly(sessionKey, { + loadGatewaySessionEntryReadOnly(sessionKey, { ...sessionLoadOptions, includeStoreChildEntries: true, }), diff --git a/src/gateway/server-methods/chat-message-get-handler.ts b/src/gateway/server-methods/chat-message-get-handler.ts index 2b80bddc8e78..a2863d96ef30 100644 --- a/src/gateway/server-methods/chat-message-get-handler.ts +++ b/src/gateway/server-methods/chat-message-get-handler.ts @@ -17,7 +17,7 @@ import { readSessionMessageByIdAsync, readSessionMessagesAsync, } from "../session-transcript-readers.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import { readChatHistoryMessageId } from "./chat-history-pages.js"; import { resolveRequestedChatAgentId, validateChatSelectedAgent } from "./chat-origin-routing.js"; import { normalizeOptionalChatText as normalizeOptionalText } from "./chat-text-normalization.js"; @@ -74,7 +74,10 @@ export const chatMessageGetHandlers: GatewayRequestHandlers = { agentId: agentIdOverride, }); const sessionLoadOptions = requestedAgentId ? { agentId: requestedAgentId } : undefined; - const { cfg, storePath, entry } = loadSessionEntryReadOnly(sessionKey, sessionLoadOptions); + const { cfg, storePath, entry } = loadGatewaySessionEntryReadOnly( + sessionKey, + sessionLoadOptions, + ); const selectedAgent = validateChatSelectedAgent({ cfg, requestedSessionKey: sessionKey, diff --git a/src/gateway/server-methods/chat.directive-tags.test.ts b/src/gateway/server-methods/chat.directive-tags.test.ts index 3bb6388a5d0c..19acbf091ebc 100644 --- a/src/gateway/server-methods/chat.directive-tags.test.ts +++ b/src/gateway/server-methods/chat.directive-tags.test.ts @@ -256,7 +256,7 @@ vi.mock("../session-utils.js", async () => { return { ...original, loadSessionEntry, - loadSessionEntryReadOnly: loadSessionEntry, + loadGatewaySessionEntryReadOnly: loadSessionEntry, }; }); diff --git a/src/gateway/server-methods/chat.ts b/src/gateway/server-methods/chat.ts index 487e92132d86..cf9bde1228ed 100644 --- a/src/gateway/server-methods/chat.ts +++ b/src/gateway/server-methods/chat.ts @@ -17,7 +17,7 @@ import { import { resolveSessionSubscriptionKeys } from "../session-subscription-keys.js"; import { loadSessionEntry, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, resolveSessionModelRef, } from "../session-utils.js"; import { formatForLog } from "../ws-log.js"; @@ -84,7 +84,7 @@ export const chatHandlers: GatewayRequestHandlers = { // Session entry carries per-session model overrides; utility routing must // derive its small-model default from the provider this session actually // uses, not the agent's configured default. - const { cfg: sessionCfg, entry } = loadSessionEntryReadOnly( + const { cfg: sessionCfg, entry } = loadGatewaySessionEntryReadOnly( params.sessionKey, selectedAgent.agentId ? { agentId: selectedAgent.agentId } : undefined, ); diff --git a/src/gateway/server-methods/cron.ts b/src/gateway/server-methods/cron.ts index 6212d3c04308..b8f9d5305c68 100644 --- a/src/gateway/server-methods/cron.ts +++ b/src/gateway/server-methods/cron.ts @@ -54,7 +54,7 @@ import { import { parseAgentSessionKey } from "../../sessions/session-key-utils.js"; import { consumeCronCreatorAuthorityGrant } from "../cron-creator-authority-grant.js"; import { getGatewayProcessInstanceId } from "../process-instance.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import { assertActiveAgentRuntimeAuthority, hasActiveAgentRuntimeAuthority, @@ -342,7 +342,7 @@ function assertCronDoesNotTargetAgentHarness(input: { return; } - const loaded = loadSessionEntryReadOnly( + const loaded = loadGatewaySessionEntryReadOnly( targetSessionKey, input.agentId?.trim() ? { agentId: input.agentId.trim() } : {}, ); @@ -405,7 +405,7 @@ export const cronHandlers: GatewayRequestHandlers = { const sessionKey = p.sessionKey?.trim() || undefined; const agentId = p.agentId?.trim() || undefined; if (sessionKey && isAgentHarnessSessionKey(sessionKey)) { - const loaded = loadSessionEntryReadOnly(sessionKey, agentId ? { agentId } : {}); + const loaded = loadGatewaySessionEntryReadOnly(sessionKey, agentId ? { agentId } : {}); const harnessSessionError = loaded.entry ? resolveAgentHarnessSessionStoreEntryError(loaded.canonicalKey, loaded.entry) : AGENT_HARNESS_SESSION_KEY_RESERVED_MESSAGE; diff --git a/src/gateway/server-methods/cron.validation.test.ts b/src/gateway/server-methods/cron.validation.test.ts index 7a29b33bc4e2..832fbd28b652 100644 --- a/src/gateway/server-methods/cron.validation.test.ts +++ b/src/gateway/server-methods/cron.validation.test.ts @@ -52,7 +52,7 @@ vi.mock("../../config/config.js", async () => { vi.mock("../session-utils.js", () => ({ loadSessionEntry: loadGatewaySessionEntry, - loadSessionEntryReadOnly: loadGatewaySessionEntry, + loadGatewaySessionEntryReadOnly: loadGatewaySessionEntry, })); import { cronHandlers } from "./cron.js"; diff --git a/src/gateway/server-methods/deleted-agent-guard.test-helpers.ts b/src/gateway/server-methods/deleted-agent-guard.test-helpers.ts index e7f788455e10..95f6bc0befd3 100644 --- a/src/gateway/server-methods/deleted-agent-guard.test-helpers.ts +++ b/src/gateway/server-methods/deleted-agent-guard.test-helpers.ts @@ -5,20 +5,20 @@ import { vi } from "vitest"; const deletedAgentSessionMocks = vi.hoisted(() => ({ loadSessionEntry: vi.fn(), - loadSessionEntryReadOnly: vi.fn(), + loadGatewaySessionEntryReadOnly: vi.fn(), resolveDeletedAgentIdFromSessionKey: vi.fn(), })); vi.mock("../session-utils.js", () => ({ loadSessionEntry: deletedAgentSessionMocks.loadSessionEntry, - loadSessionEntryReadOnly: deletedAgentSessionMocks.loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly: deletedAgentSessionMocks.loadGatewaySessionEntryReadOnly, resolveDeletedAgentIdFromSessionKey: deletedAgentSessionMocks.resolveDeletedAgentIdFromSessionKey, })); /** Resets mocked deleted-agent session lookups between tests. */ export function resetDeletedAgentSessionMocks(): void { deletedAgentSessionMocks.loadSessionEntry.mockReset(); - deletedAgentSessionMocks.loadSessionEntryReadOnly.mockReset(); + deletedAgentSessionMocks.loadGatewaySessionEntryReadOnly.mockReset(); deletedAgentSessionMocks.resolveDeletedAgentIdFromSessionKey.mockReset(); } diff --git a/src/gateway/server-methods/sessions-create.ts b/src/gateway/server-methods/sessions-create.ts index 47c6a256d709..e5167ce1196b 100644 --- a/src/gateway/server-methods/sessions-create.ts +++ b/src/gateway/server-methods/sessions-create.ts @@ -36,7 +36,10 @@ import type { PrepareGatewaySessionLifecycle } from "../session-lifecycle-prepar import { resolveRequestedSessionAgentId as resolveRequestedGlobalAgentId } from "../session-request-agent.js"; import { resolveSessionStoreAgentId } from "../session-store-key.js"; import { readSessionMessageCountAsync } from "../session-transcript-readers.js"; -import { loadSessionEntryReadOnly, resolveGatewaySessionStoreTarget } from "../session-utils.js"; +import { + loadGatewaySessionEntryReadOnly, + resolveGatewaySessionStoreTarget, +} from "../session-utils.js"; import { resolveSessionPatchModelSelection } from "../sessions-patch.js"; import { createAgentRuntimeAuthorityGuard } from "./agent-runtime-authority.js"; import { chatHandlers } from "./chat.js"; @@ -288,7 +291,7 @@ export const sessionCreateHandlers: GatewayRequestHandlers = { !hasInitialTurn && cfg.session?.dmScope === "main" ) { - const parent = loadSessionEntryReadOnly( + const parent = loadGatewaySessionEntryReadOnly( parentSessionKey, requestedAgent.agentId ? { agentId: requestedAgent.agentId } : undefined, ); diff --git a/src/gateway/server-methods/sessions-diff.test.ts b/src/gateway/server-methods/sessions-diff.test.ts index 03de1d39cd7b..d78163d0faa5 100644 --- a/src/gateway/server-methods/sessions-diff.test.ts +++ b/src/gateway/server-methods/sessions-diff.test.ts @@ -25,7 +25,7 @@ const hoisted = vi.hoisted(() => ({ vi.mock("../session-utils.js", () => ({ loadSessionEntry: hoisted.loadSessionEntry, - loadSessionEntryReadOnly: hoisted.loadSessionEntry, + loadGatewaySessionEntryReadOnly: hoisted.loadSessionEntry, })); vi.mock("../../agents/agent-scope.js", () => ({ diff --git a/src/gateway/server-methods/sessions-diff.ts b/src/gateway/server-methods/sessions-diff.ts index f58f4119e3bd..c93b0a06a80c 100644 --- a/src/gateway/server-methods/sessions-diff.ts +++ b/src/gateway/server-methods/sessions-diff.ts @@ -9,7 +9,7 @@ import { import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js"; import { normalizeAgentId, parseAgentSessionKey } from "../../routing/session-key.js"; import { applySessionDiffBaseline, loadCheckoutDiff } from "../../sessions/session-diff.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import type { GatewayRequestHandlers } from "./types.js"; import { assertValidParams } from "./validation.js"; @@ -25,9 +25,12 @@ export async function loadSessionDiff(params: SessionsDiffParams): Promise { return { ...actual, loadSessionEntry: hoisted.loadSessionEntry, - loadSessionEntryReadOnly: hoisted.loadSessionEntry, + loadGatewaySessionEntryReadOnly: hoisted.loadSessionEntry, }; }); diff --git a/src/gateway/server-methods/sessions-files.touched-files.test.ts b/src/gateway/server-methods/sessions-files.touched-files.test.ts index cfe956a655cd..7337c7e6e79d 100644 --- a/src/gateway/server-methods/sessions-files.touched-files.test.ts +++ b/src/gateway/server-methods/sessions-files.touched-files.test.ts @@ -32,7 +32,7 @@ vi.mock("../session-utils.js", async () => { return { ...actual, loadSessionEntry: hoisted.loadSessionEntry, - loadSessionEntryReadOnly: hoisted.loadSessionEntry, + loadGatewaySessionEntryReadOnly: hoisted.loadSessionEntry, }; }); diff --git a/src/gateway/server-methods/sessions-files.ts b/src/gateway/server-methods/sessions-files.ts index e2e0a53f88cc..b64110a7806f 100644 --- a/src/gateway/server-methods/sessions-files.ts +++ b/src/gateway/server-methods/sessions-files.ts @@ -31,7 +31,7 @@ import { toTranscriptReadScope, type SessionTranscriptReadScope, } from "../session-transcript-readers.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import { execOpenPath, formatOpenPathError, @@ -526,7 +526,7 @@ async function toSessionFileEntry( } function loadSessionFileRoot(params: { sessionKey: string; agentId?: string }) { - const loaded = loadSessionEntryReadOnly(params.sessionKey, { agentId: params.agentId }); + const loaded = loadGatewaySessionEntryReadOnly(params.sessionKey, { agentId: params.agentId }); if (!loaded.entry?.sessionId) { return { ...loaded, agentId: undefined, root: undefined, fileRoot: undefined }; } diff --git a/src/gateway/server-methods/sessions-messaging.ts b/src/gateway/server-methods/sessions-messaging.ts index 8c9fd5295ad6..1763314b5172 100644 --- a/src/gateway/server-methods/sessions-messaging.ts +++ b/src/gateway/server-methods/sessions-messaging.ts @@ -22,7 +22,7 @@ import { reactivateCompletedSubagentSession } from "../session-subagent-reactiva import { readSessionMessageCountAsync } from "../session-transcript-readers.js"; import { loadSessionEntry, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, resolveDeletedAgentIdFromSessionKey, } from "../session-utils.js"; import { asWorkerInferenceControl } from "../worker-environments/inference-control.js"; @@ -193,7 +193,7 @@ async function createAgentMainSessionForSend(params: { } const createdKey = normalizeOptionalString(createResult.payload?.key) ?? params.canonicalKey; - const loaded = loadSessionEntryReadOnly(createdKey); + const loaded = loadGatewaySessionEntryReadOnly(createdKey); if (!loaded.entry?.sessionId) { return { ok: false, diff --git a/src/gateway/server-methods/sessions.abort-agent-scope.test.ts b/src/gateway/server-methods/sessions.abort-agent-scope.test.ts index 123f62e896b9..2ead800f799c 100644 --- a/src/gateway/server-methods/sessions.abort-agent-scope.test.ts +++ b/src/gateway/server-methods/sessions.abort-agent-scope.test.ts @@ -49,7 +49,7 @@ vi.mock("../session-utils.js", async () => { loadCombinedSessionStoreForGatewayMock(...args), loadSessionEntry: (...args: unknown[]) => loadSessionEntryMock(...(args as [string, { agentId?: string }?])), - loadSessionEntryReadOnly: (...args: unknown[]) => + loadGatewaySessionEntryReadOnly: (...args: unknown[]) => loadSessionEntryMock(...(args as [string, { agentId?: string }?])), loadGatewaySessionRow: (...args: unknown[]) => loadGatewaySessionRowMock(...args), }; diff --git a/src/gateway/server-methods/sessions.messages-subscribe-approvals.test.ts b/src/gateway/server-methods/sessions.messages-subscribe-approvals.test.ts index aa5c802d4bc0..0e3c52e735c0 100644 --- a/src/gateway/server-methods/sessions.messages-subscribe-approvals.test.ts +++ b/src/gateway/server-methods/sessions.messages-subscribe-approvals.test.ts @@ -17,7 +17,7 @@ vi.mock("../session-utils.js", async () => { ...actual, loadSessionEntry: (...args: unknown[]) => loadSessionEntryMock(...(args as [string, { agentId?: string }?])), - loadSessionEntryReadOnly: (...args: unknown[]) => + loadGatewaySessionEntryReadOnly: (...args: unknown[]) => loadSessionEntryMock(...(args as [string, { agentId?: string }?])), }; }); diff --git a/src/gateway/server-methods/sessions.send-followup-status.test.ts b/src/gateway/server-methods/sessions.send-followup-status.test.ts index a0b6999fa915..0cd84f0b0735 100644 --- a/src/gateway/server-methods/sessions.send-followup-status.test.ts +++ b/src/gateway/server-methods/sessions.send-followup-status.test.ts @@ -11,7 +11,7 @@ import { expectSubagentFollowupReactivation } from "./subagent-followup.test-hel import type { GatewayRequestContext, RespondFn } from "./types.js"; const loadSessionEntryMock = vi.fn(); -const loadSessionEntryReadOnlyMock = vi.fn(); +const loadGatewaySessionEntryReadOnlyMock = vi.fn(); const readSessionMessageCountAsyncMock = vi.fn(); const loadGatewaySessionRowMock = vi.fn(); const resolveDeletedAgentIdFromSessionKeyMock = vi.fn(); @@ -49,7 +49,8 @@ vi.mock("../../auto-reply/reply/queue/cleanup.js", async () => { vi.mock("../session-utils.js", () => ({ loadSessionEntry: (...args: unknown[]) => loadSessionEntryMock(...args), - loadSessionEntryReadOnly: (...args: unknown[]) => loadSessionEntryReadOnlyMock(...args), + loadGatewaySessionEntryReadOnly: (...args: unknown[]) => + loadGatewaySessionEntryReadOnlyMock(...args), loadGatewaySessionRow: (...args: unknown[]) => loadGatewaySessionRowMock(...args), resolveDeletedAgentIdFromSessionKey: (...args: unknown[]) => resolveDeletedAgentIdFromSessionKeyMock(...args), @@ -113,7 +114,7 @@ function createRequestContext(overrides: Record = {}): GatewayR describe("sessions.send completed subagent follow-up status", () => { beforeEach(() => { loadSessionEntryMock.mockReset(); - loadSessionEntryReadOnlyMock.mockReset(); + loadGatewaySessionEntryReadOnlyMock.mockReset(); readSessionMessageCountAsyncMock.mockReset().mockResolvedValue(0); loadGatewaySessionRowMock.mockReset(); resolveDeletedAgentIdFromSessionKeyMock.mockReset().mockReturnValue(null); diff --git a/src/gateway/server-methods/task-suggestions.test.ts b/src/gateway/server-methods/task-suggestions.test.ts index cd48db757915..00e7c8737ec5 100644 --- a/src/gateway/server-methods/task-suggestions.test.ts +++ b/src/gateway/server-methods/task-suggestions.test.ts @@ -23,11 +23,13 @@ vi.mock("../session-utils.js", async (importOriginal) => { const actual = await importOriginal(); return { ...actual, - loadSessionEntryReadOnly: (...args: Parameters) => { + loadGatewaySessionEntryReadOnly: ( + ...args: Parameters + ) => { if (sessionReadState.mode === "throw") { throw new Error("session inspection unavailable"); } - const loaded = actual.loadSessionEntryReadOnly(...args); + const loaded = actual.loadGatewaySessionEntryReadOnly(...args); return sessionReadState.mode === "present" ? { ...loaded, entry: { sessionId: "surviving-session", updatedAt: 1 } } : loaded; diff --git a/src/gateway/server-methods/task-suggestions.ts b/src/gateway/server-methods/task-suggestions.ts index 622fad48a1e5..4b86282fa490 100644 --- a/src/gateway/server-methods/task-suggestions.ts +++ b/src/gateway/server-methods/task-suggestions.ts @@ -18,7 +18,7 @@ import { resolveSessionWorkStartError } from "../../config/sessions.js"; import { formatErrorMessage } from "../../infra/errors.js"; import { normalizeAgentId, parseAgentSessionKey } from "../../routing/session-key.js"; import { buildDashboardSessionKey } from "../session-create-service.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import { abandonTaskSuggestionAcceptance, beginTaskSuggestionAcceptance, @@ -107,7 +107,7 @@ async function rollbackSuggestedTaskSession(params: { return false; } try { - return !loadSessionEntryReadOnly(params.key, { agentId: params.agentId }).entry; + return !loadGatewaySessionEntryReadOnly(params.key, { agentId: params.agentId }).entry; } catch { return false; } @@ -358,9 +358,9 @@ async function deliverSuggestedTaskToSourceSession(params: { const agentId = resolveSuggestionAgentId(params.suggestion, params.options); const fail = (error: NonNullable[2]>) => failSuggestedTaskDelivery({ taskId: params.taskId, options: params.options, error }); - let source: ReturnType; + let source: ReturnType; try { - source = loadSessionEntryReadOnly(params.suggestion.sessionKey, { agentId }); + source = loadGatewaySessionEntryReadOnly(params.suggestion.sessionKey, { agentId }); } catch (error) { return fail(errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error))); } diff --git a/src/gateway/server-methods/tools-effective.runtime.ts b/src/gateway/server-methods/tools-effective.runtime.ts index 78d6fa251088..3df04d4830a5 100644 --- a/src/gateway/server-methods/tools-effective.runtime.ts +++ b/src/gateway/server-methods/tools-effective.runtime.ts @@ -25,4 +25,4 @@ export { getActivePluginRegistryVersion, } from "../../plugins/runtime.js"; export { deliveryContextFromSession } from "../../utils/delivery-context.shared.js"; -export { loadSessionEntryReadOnly, resolveSessionModelRef } from "../session-utils.js"; +export { loadGatewaySessionEntryReadOnly, resolveSessionModelRef } from "../session-utils.js"; diff --git a/src/gateway/server-methods/tools-effective.test.ts b/src/gateway/server-methods/tools-effective.test.ts index 76ff04487639..532824ef8795 100644 --- a/src/gateway/server-methods/tools-effective.test.ts +++ b/src/gateway/server-methods/tools-effective.test.ts @@ -75,7 +75,7 @@ const runtimeMocks = vi.hoisted(() => ({ vi.mock("./tools-effective.runtime.js", () => ({ ...runtimeMocks, - loadSessionEntryReadOnly: runtimeMocks.loadSessionEntry, + loadGatewaySessionEntryReadOnly: runtimeMocks.loadSessionEntry, })); const nodePluginToolSnapshotMocks = vi.hoisted(() => ({ diff --git a/src/gateway/server-methods/tools-effective.ts b/src/gateway/server-methods/tools-effective.ts index 2fbe974c4c3b..91190a45fb46 100644 --- a/src/gateway/server-methods/tools-effective.ts +++ b/src/gateway/server-methods/tools-effective.ts @@ -29,7 +29,7 @@ import { getActivePluginRegistryVersion, getRegisteredAgentHarness, listAgentIds, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, peekSessionMcpRuntime, resolveAgentDir, resolveAgentWorkspaceDir, @@ -531,7 +531,7 @@ function resolveTrustedToolsEffectiveContext(params: { }) { // The effective tools request is read-only but security-sensitive. Derive // routing/account/model context from the persisted session, not client params. - const loaded = loadSessionEntryReadOnly( + const loaded = loadGatewaySessionEntryReadOnly( params.sessionKey, params.requestedAgentId ? { agentId: params.requestedAgentId } : undefined, ); diff --git a/src/gateway/server-methods/usage.sessions-usage.test.ts b/src/gateway/server-methods/usage.sessions-usage.test.ts index 4e50230c9082..4fdd48c99c8a 100644 --- a/src/gateway/server-methods/usage.sessions-usage.test.ts +++ b/src/gateway/server-methods/usage.sessions-usage.test.ts @@ -23,7 +23,7 @@ vi.mock("../session-utils.js", async () => { const actual = await vi.importActual("../session-utils.js"); return { ...actual, - loadSessionEntryReadOnly: vi.fn(actual.loadSessionEntryReadOnly), + loadGatewaySessionEntryReadOnly: vi.fn(actual.loadGatewaySessionEntryReadOnly), loadCombinedSessionStoreForGatewayCore: vi.fn(() => ({ storePath: "(multiple)", store: {} })), }; }); @@ -106,7 +106,7 @@ import { } from "../../infra/session-cost-usage.js"; import { loadCombinedSessionStoreForGatewayCore, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, } from "../session-utils.js"; import { testApi, usageHandlers } from "./usage.js"; @@ -190,7 +190,7 @@ function expectSuccessfulSessionsUsage( function mockStoredSession(key: string, sessionId: string) { const entry = { sessionId, updatedAt: 1_000 }; - vi.mocked(loadSessionEntryReadOnly).mockReturnValueOnce({ + vi.mocked(loadGatewaySessionEntryReadOnly).mockReturnValueOnce({ cfg: TEST_RUNTIME_CONFIG, canonicalKey: key, entry, diff --git a/src/gateway/server-methods/usage.ts b/src/gateway/server-methods/usage.ts index 9994721cea49..3f1b841e1fcf 100644 --- a/src/gateway/server-methods/usage.ts +++ b/src/gateway/server-methods/usage.ts @@ -68,7 +68,7 @@ import { } from "../session-store-key.js"; import { loadCombinedSessionStoreForGatewayCore, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, } from "../session-utils.js"; import { loadUsageStatusStaleWhileRevalidate } from "./models-auth-status-usage-cache.js"; import type { GatewayRequestHandlers, RespondFn } from "./types.js"; @@ -135,7 +135,7 @@ function resolveSessionUsageTarget( config: OpenClawConfig, agentIdHint?: string, ): ResolvedSessionUsageTarget | undefined { - const { canonicalKey, entry, storePath } = loadSessionEntryReadOnly( + const { canonicalKey, entry, storePath } = loadGatewaySessionEntryReadOnly( key, agentIdHint ? { agentId: agentIdHint } : undefined, ); diff --git a/src/gateway/server-session-events.test.ts b/src/gateway/server-session-events.test.ts index 157b3f99b391..c72b548e2a86 100644 --- a/src/gateway/server-session-events.test.ts +++ b/src/gateway/server-session-events.test.ts @@ -35,7 +35,7 @@ vi.mock("./session-utils.js", () => ({ attachOpenClawTranscriptMeta: (message: unknown) => message, loadGatewaySessionRow: loadGatewaySessionRowMock, loadSessionEntry: () => ({ entry: undefined, storePath: "" }), - loadSessionEntryReadOnly: loadGatewaySessionEntryReadOnlyMock, + loadGatewaySessionEntryReadOnly: loadGatewaySessionEntryReadOnlyMock, })); vi.mock("./session-transcript-readers.js", async (importOriginal) => { const actual = await importOriginal(); diff --git a/src/gateway/server-session-events.ts b/src/gateway/server-session-events.ts index febec53791ff..d437494e3c5d 100644 --- a/src/gateway/server-session-events.ts +++ b/src/gateway/server-session-events.ts @@ -35,7 +35,7 @@ import { } from "./session-transcript-readers.js"; import { loadGatewaySessionRow, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, type GatewaySessionRow, } from "./session-utils.js"; @@ -84,7 +84,7 @@ function readTranscriptUpdateLifecycleOwner( const storePath = normalizeOptionalString(update.target?.storePath) ?? marker?.storePath; const entry = storePath ? loadAccessorSessionEntryReadOnly({ agentId, sessionKey, storePath }) - : loadSessionEntryReadOnly(sessionKey, agentId ? { agentId } : undefined)?.entry; + : loadGatewaySessionEntryReadOnly(sessionKey, agentId ? { agentId } : undefined)?.entry; if (!entry || (sessionId && entry.sessionId !== sessionId)) { return undefined; } @@ -300,7 +300,7 @@ async function handleTranscriptUpdateBroadcast( }), storePath: updateStorePath, } - : loadSessionEntryReadOnly(sessionKey, { agentId: routingAgentId }); + : loadGatewaySessionEntryReadOnly(sessionKey, { agentId: routingAgentId }); const entry = fallbackTarget?.entry; const messageSessionId = compatibleLegacyMarker?.sessionId ?? diff --git a/src/gateway/session-companion-context.ts b/src/gateway/session-companion-context.ts index 25eb66e09a8f..ee81848baf42 100644 --- a/src/gateway/session-companion-context.ts +++ b/src/gateway/session-companion-context.ts @@ -12,7 +12,7 @@ import type { SessionCompanionContextMessage, SessionCompanionPreparedContext, } from "./session-companion-state.js"; -import { loadSessionEntryReadOnly } from "./session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "./session-utils.js"; const CONTEXT_MAX_MESSAGES = 40; const CONTEXT_MAX_BYTES = 24 * 1024; @@ -123,7 +123,7 @@ async function readSessionCompanionContext(params: { sessionKey: string; signal?: AbortSignal; }): Promise { - const loaded = loadSessionEntryReadOnly(params.sessionKey, { agentId: params.agentId }); + const loaded = loadGatewaySessionEntryReadOnly(params.sessionKey, { agentId: params.agentId }); const sessionId = loaded.entry?.sessionId?.trim(); if (!sessionId) { return { kind: "missing" }; @@ -229,6 +229,6 @@ async function readSessionCompanionContext(params: { export const defaultSessionCompanionContextReader: SessionCompanionContextReader = { currentSessionId: ({ agentId, sessionKey }) => - loadSessionEntryReadOnly(sessionKey, { agentId }).entry?.sessionId?.trim() || undefined, + loadGatewaySessionEntryReadOnly(sessionKey, { agentId }).entry?.sessionId?.trim() || undefined, read: readSessionCompanionContext, }; diff --git a/src/gateway/session-create-service.ts b/src/gateway/session-create-service.ts index 345f309ce4b9..a08cf8d9c8d5 100644 --- a/src/gateway/session-create-service.ts +++ b/src/gateway/session-create-service.ts @@ -85,7 +85,10 @@ import { resolvePluginSessionOwnershipError } from "./session-plugin-ownership.j import { resolveRequestedSessionAgentId } from "./session-request-agent.js"; import { isSessionVisibilityAllowed, resolveSessionVisibility } from "./session-sharing.js"; import { resolveSessionStoreKey } from "./session-store-key.js"; -import { loadSessionEntryReadOnly, resolveGatewaySessionStoreTarget } from "./session-utils.js"; +import { + loadGatewaySessionEntryReadOnly, + resolveGatewaySessionStoreTarget, +} from "./session-utils.js"; import { projectSessionsPatchEntry, resolveSessionPatchModelSelection } from "./sessions-patch.js"; type TrustedCatalogSessionTarget = { @@ -384,7 +387,7 @@ export async function createGatewaySession(params: { agentId, storePath: durableStorePath, }).some(({ sessionKey }) => sessionKey === explicitTargetKey); - if (durableEntryExists || loadSessionEntryReadOnly(explicitTargetKey).entry) { + if (durableEntryExists || loadGatewaySessionEntryReadOnly(explicitTargetKey).entry) { return { ok: false, error: errorShape( @@ -491,7 +494,7 @@ export async function createGatewaySession(params: { } parentSelectedAgentId = parentRequestedAgent.agentId; } - const parent = loadSessionEntryReadOnly( + const parent = loadGatewaySessionEntryReadOnly( parentSessionKey, parentSelectedAgentId ? { agentId: parentSelectedAgentId } : undefined, ); @@ -708,7 +711,7 @@ export async function createGatewaySession(params: { params.fork === true || params.authorizedPluginId !== undefined) ) { - const currentParent = loadSessionEntryReadOnly( + const currentParent = loadGatewaySessionEntryReadOnly( canonicalParentSessionKey, parentSelectedAgentId ? { agentId: parentSelectedAgentId } : undefined, ); @@ -793,7 +796,7 @@ export async function createGatewaySession(params: { } const target = creationTarget; - const currentTargetEntry = loadSessionEntryReadOnly(target.canonicalKey, { + const currentTargetEntry = loadGatewaySessionEntryReadOnly(target.canonicalKey, { agentId: target.agentId, }).entry; const preparationResult = params.prepareLifecycle diff --git a/src/gateway/session-utils.test.ts b/src/gateway/session-utils.test.ts index 193a0715fa98..8b3f4cea3553 100644 --- a/src/gateway/session-utils.test.ts +++ b/src/gateway/session-utils.test.ts @@ -36,7 +36,7 @@ import { listSessionsFromStore, listSessionsFromStoreAsync, loadSessionEntry, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, resolveCanonicalGatewaySessionStoreKey, resolveDeletedAgentIdFromSessionKey, resolveGatewayModelSupportsImages, @@ -2210,7 +2210,7 @@ describe("gateway session utils", () => { } }); - test("loadSessionEntryReadOnly does not materialize a missing configured agent", async () => { + test("loadGatewaySessionEntryReadOnly does not materialize a missing configured agent", async () => { resetConfigRuntimeState(); try { await withStateDirEnv("session-utils-load-entry-read-only-", async ({ stateDir }) => { @@ -2223,7 +2223,7 @@ describe("gateway session utils", () => { } as OpenClawConfig; setRuntimeConfigSnapshot(cfg, cfg); - const loaded = loadSessionEntryReadOnly("agent:missing:main"); + const loaded = loadGatewaySessionEntryReadOnly("agent:missing:main"); expect(loaded.entry).toBeUndefined(); expect(fs.existsSync(path.join(stateDir, "agents", "missing"))).toBe(false); @@ -2233,7 +2233,7 @@ describe("gateway session utils", () => { } }); - test("loadSessionEntryReadOnly clones only the selected row and direct children", async () => { + test("loadGatewaySessionEntryReadOnly clones only the selected row and direct children", async () => { resetConfigRuntimeState(); try { await withStateDirEnv("session-utils-exact-read-only-", async ({ stateDir }) => { @@ -2261,7 +2261,7 @@ describe("gateway session utils", () => { ).toContain(childKey); const cloneSpy = vi.spyOn(globalThis, "structuredClone"); try { - expect(loadSessionEntryReadOnly(childKey, { clone: false }).entry).toMatchObject({ + expect(loadGatewaySessionEntryReadOnly(childKey, { clone: false }).entry).toMatchObject({ sessionId: "child", spawnedBy: parentKey, }); @@ -2273,7 +2273,7 @@ describe("gateway session utils", () => { storePath, }).map((item) => item.sessionKey), ).toEqual([childKey]); - const loaded = loadSessionEntryReadOnly("main", { + const loaded = loadGatewaySessionEntryReadOnly("main", { includeStoreChildEntries: true, }); @@ -2322,7 +2322,7 @@ describe("gateway session utils", () => { expect(spawnedByReads).toBe(1); }); - test("loadSessionEntryReadOnly rejects a persisted main alias", async () => { + test("loadGatewaySessionEntryReadOnly rejects a persisted main alias", async () => { resetConfigRuntimeState(); try { await withStateDirEnv("session-utils-exact-alias-children-", async ({ stateDir }) => { @@ -2345,7 +2345,7 @@ describe("gateway session utils", () => { setRuntimeConfigSnapshot(cfg, cfg); expect(() => - loadSessionEntryReadOnly("main", { + loadGatewaySessionEntryReadOnly("main", { clone: false, includeStoreChildEntries: true, }), diff --git a/src/gateway/session-utils.ts b/src/gateway/session-utils.ts index efb0049f895c..d97dbdd74807 100644 --- a/src/gateway/session-utils.ts +++ b/src/gateway/session-utils.ts @@ -15,7 +15,7 @@ export { loadCombinedSessionStoreForGatewayCore } from "../config/sessions/combi export { deriveSessionTitle } from "./session-utils-core.js"; export { resolveDeletedAgentIdFromSessionKey } from "./session-utils-store.js"; export { loadGatewaySessionEntry as loadSessionEntry } from "./session-utils-store.js"; -export { loadGatewaySessionEntryReadOnly as loadSessionEntryReadOnly } from "./session-utils-store.js"; +export { loadGatewaySessionEntryReadOnly } from "./session-utils-store.js"; export { resolveCanonicalSessionStoreMatchFromStoreKeys } from "./session-utils-store.js"; export { resolveCanonicalSessionEntryFromStoreKeys } from "./session-utils-store.js"; export { resolveCanonicalGatewaySessionStoreKey } from "./session-utils-store.js"; diff --git a/src/gateway/worker-environments/worker-session-tool-executor.test.ts b/src/gateway/worker-environments/worker-session-tool-executor.test.ts index b13c4ec90d0f..382bcf8fb04f 100644 --- a/src/gateway/worker-environments/worker-session-tool-executor.test.ts +++ b/src/gateway/worker-environments/worker-session-tool-executor.test.ts @@ -28,7 +28,7 @@ vi.mock("../session-utils.js", async (importOriginal) => { const actual = await importOriginal(); return { ...actual, - loadSessionEntryReadOnly: (sessionKey: string) => ({ + loadGatewaySessionEntryReadOnly: (sessionKey: string) => ({ canonicalKey: sessionKey, entry: structuredClone(sessionEntries.get(sessionKey)), }), diff --git a/src/gateway/worker-environments/worker-session-tool-executor.ts b/src/gateway/worker-environments/worker-session-tool-executor.ts index 003a75b5467d..a603697cef50 100644 --- a/src/gateway/worker-environments/worker-session-tool-executor.ts +++ b/src/gateway/worker-environments/worker-session-tool-executor.ts @@ -23,7 +23,7 @@ import { sha256Base64Url } from "../../infra/crypto-digest.js"; import { redactSensitiveText } from "../../logging/redact.js"; import { normalizeAgentId } from "../../routing/session-key.js"; import { WORKER_TOOL_NAMES } from "../../worker/tool-authority.js"; -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import type { WorkerConnectionIdentity } from "./connection-identity.js"; import type { WorkerSessionPlacementStore } from "./placement-store.js"; import type { WorkerPlacementDispatchContract } from "./service-contract.js"; @@ -150,7 +150,9 @@ export function createWorkerSessionToolExecutor(params: { } throwIfAborted(operation.signal); exactSource({ identity: operation.identity, placements: params.placements }); - let loaded = loadSessionEntryReadOnly(operation.childSessionKey, { agentId: targetAgentId }); + let loaded = loadGatewaySessionEntryReadOnly(operation.childSessionKey, { + agentId: targetAgentId, + }); let createResponse: Record; let creationAttempted = false; if (loaded.entry?.sessionId) { @@ -192,7 +194,7 @@ export function createWorkerSessionToolExecutor(params: { }, ); } catch (error) { - loaded = loadSessionEntryReadOnly(operation.childSessionKey, { + loaded = loadGatewaySessionEntryReadOnly(operation.childSessionKey, { agentId: targetAgentId, }); if (!loaded.entry?.sessionId) { @@ -205,7 +207,9 @@ export function createWorkerSessionToolExecutor(params: { entry: loaded.entry, }; } - loaded = loadSessionEntryReadOnly(operation.childSessionKey, { agentId: targetAgentId }); + loaded = loadGatewaySessionEntryReadOnly(operation.childSessionKey, { + agentId: targetAgentId, + }); } const childSessionId = loaded.entry?.sessionId; if (!childSessionId) { diff --git a/src/gateway/worker-environments/worker-session-tool-topology.ts b/src/gateway/worker-environments/worker-session-tool-topology.ts index 857f49c2849c..5cf224fe8000 100644 --- a/src/gateway/worker-environments/worker-session-tool-topology.ts +++ b/src/gateway/worker-environments/worker-session-tool-topology.ts @@ -1,4 +1,4 @@ -import { loadSessionEntryReadOnly } from "../session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../session-utils.js"; import type { WorkerConnectionIdentity } from "./connection-identity.js"; import type { WorkerSessionPlacementStore } from "./placement-store.js"; @@ -14,7 +14,7 @@ export type WorkerSessionToolSource = { ownerEpoch: number; runId: string; }; - entry: NonNullable["entry"]>; + entry: NonNullable["entry"]>; }; export type WorkerSessionToolTarget = { @@ -54,7 +54,9 @@ export function resolveWorkerSessionToolSource(params: { ) { throw new Error("Worker source session placement changed"); } - const loaded = loadSessionEntryReadOnly(placement.sessionKey, { agentId: placement.agentId }); + const loaded = loadGatewaySessionEntryReadOnly(placement.sessionKey, { + agentId: placement.agentId, + }); if ( loaded.canonicalKey !== placement.sessionKey || loaded.entry?.sessionId !== identity.sessionId || @@ -83,7 +85,7 @@ export function resolveWorkerSessionToolTarget(params: { requestedSessionKey: string; placements: WorkerSessionPlacementStore; }): WorkerSessionToolTarget { - const loaded = loadSessionEntryReadOnly(params.requestedSessionKey); + const loaded = loadGatewaySessionEntryReadOnly(params.requestedSessionKey); const entry = loaded.entry; const targetSessionId = entry?.sessionId; if ( @@ -111,7 +113,7 @@ export function resolveWorkerSessionToolTarget(params: { ); const parent = sharedParentIncarnation && sourceParent && sourceParentId - ? loadSessionEntryReadOnly(sourceParent) + ? loadGatewaySessionEntryReadOnly(sourceParent) : undefined; const siblingToSibling = Boolean( parent && @@ -147,7 +149,7 @@ export function assertWorkerSessionToolChild(params: { sourceSessionId: string; targetAgentId: string; }): void { - const loaded = loadSessionEntryReadOnly(params.childSessionKey, { + const loaded = loadGatewaySessionEntryReadOnly(params.childSessionKey, { agentId: params.targetAgentId, }); const parent = diff --git a/src/infra/json-files.ts b/src/infra/json-files.ts index 6977b388124a..5d448e45c485 100644 --- a/src/infra/json-files.ts +++ b/src/infra/json-files.ts @@ -10,19 +10,19 @@ type WriteTextAtomicBeforeRename = (params: { export { JsonFileReadError, readJson, - readJson as readJsonFileStrict, + readJson as readJsonFileStrict, // Sanctioned domain alias. readJsonIfExists, - readJsonIfExists as readDurableJsonFile, + readJsonIfExists as readDurableJsonFile, // Sanctioned domain alias. readJsonSync, readRootJsonObjectSync, readRootJsonSync, readRootStructuredFileSync, tryReadJson, - tryReadJson as readJsonFile, + tryReadJson as readJsonFile, // Sanctioned domain alias. tryReadJsonSync, - tryReadJsonSync as readJsonFileSync, + tryReadJsonSync as readJsonFileSync, // Sanctioned domain alias. writeJson, - writeJson as writeJsonAtomic, + writeJson as writeJsonAtomic, // Sanctioned domain alias. writeJsonSync, } from "@openclaw/fs-safe/json"; diff --git a/src/infra/openclaw-root.fs.runtime.ts b/src/infra/openclaw-root.fs.runtime.ts index 3e0ff74996b7..5392374bbd4f 100644 --- a/src/infra/openclaw-root.fs.runtime.ts +++ b/src/infra/openclaw-root.fs.runtime.ts @@ -1,4 +1,4 @@ // OpenClaw root resolution imports fs through this facade so tests can replace // filesystem behavior without mocking node:fs globally. -export { default as openClawRootFsSync } from "node:fs"; -export { default as openClawRootFs } from "node:fs/promises"; +export { default as openClawRootFsSync } from "node:fs"; // Sanctioned domain alias. +export { default as openClawRootFs } from "node:fs/promises"; // Sanctioned domain alias. diff --git a/src/infra/secret-file.ts b/src/infra/secret-file.ts index 965bfa878930..38685dccdc80 100644 --- a/src/infra/secret-file.ts +++ b/src/infra/secret-file.ts @@ -17,7 +17,7 @@ export { readSecretFileSync, type SecretFileReadOptions, } from "@openclaw/fs-safe/secret"; -export { writeSecretFileAtomic as writePrivateSecretFileAtomic } from "@openclaw/fs-safe/secret"; +export { writeSecretFileAtomic as writePrivateSecretFileAtomic } from "@openclaw/fs-safe/secret"; // Sanctioned domain alias. export type SecretFileReadResult = | { diff --git a/src/infra/state-migrations.workspace-setup-receipts.ts b/src/infra/state-migrations.workspace-setup-receipts.ts index 221bab43db22..4e09444fba68 100644 --- a/src/infra/state-migrations.workspace-setup-receipts.ts +++ b/src/infra/state-migrations.workspace-setup-receipts.ts @@ -5,7 +5,7 @@ import { } from "./state-migrations.receipts.js"; import type { LegacyWorkspaceStateSource } from "./state-migrations.workspace-setup.types.js"; -export { markLegacyMigrationSourceRemoved as markSourceRemoved } from "./state-migrations.receipts.js"; +export { markLegacyMigrationSourceRemoved } from "./state-migrations.receipts.js"; export type MigrationReceipt = { sourceKey: string; diff --git a/src/infra/state-migrations.workspace-setup.ts b/src/infra/state-migrations.workspace-setup.ts index 4e59eae55f6f..3bcf645776bf 100644 --- a/src/infra/state-migrations.workspace-setup.ts +++ b/src/infra/state-migrations.workspace-setup.ts @@ -27,7 +27,7 @@ import { } from "./state-migrations.source-snapshot.js"; import type { MigrationMessages } from "./state-migrations.types.js"; import { - markSourceRemoved, + markLegacyMigrationSourceRemoved, readReceipt, type MigrationReceipt, } from "./state-migrations.workspace-setup-receipts.js"; @@ -386,7 +386,7 @@ async function cleanupReceiptSource(params: { const hasClaim = await sourceClaim.exists(true); if (!hasSource && !hasClaim) { if (!params.receipt.removedSource) { - markSourceRemoved(params.receipt.sourceKey, params.env); + markLegacyMigrationSourceRemoved(params.receipt.sourceKey, params.env); } return { changes: [], warnings: [] }; } @@ -433,7 +433,7 @@ async function cleanupReceiptSource(params: { } assertConfiguredWorkspaceIdentity(params.source); await sourceClaim.remove({ skipSourceCheck: true }); - markSourceRemoved(params.receipt.sourceKey, params.env); + markLegacyMigrationSourceRemoved(params.receipt.sourceKey, params.env); return { changes: [], warnings: [], @@ -564,7 +564,7 @@ async function migrateOneSource(params: { throw new Error("legacy workspace claim changed after import"); } await sourceClaim.remove({ removeSource: params.removeSource, skipSourceCheck: true }); - markSourceRemoved(result.sourceKey, params.env); + markLegacyMigrationSourceRemoved(result.sourceKey, params.env); } catch (error) { return { changes: [], diff --git a/src/media-generation/model-ref.ts b/src/media-generation/model-ref.ts index c3500213a1b9..ea4be27cc2f3 100644 --- a/src/media-generation/model-ref.ts +++ b/src/media-generation/model-ref.ts @@ -1,3 +1,3 @@ -export { parseGenerationModelRef as parseImageGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js"; -export { parseGenerationModelRef as parseMusicGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js"; -export { parseGenerationModelRef as parseVideoGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js"; +export { parseGenerationModelRef as parseImageGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js"; // Sanctioned domain alias. +export { parseGenerationModelRef as parseMusicGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js"; // Sanctioned domain alias. +export { parseGenerationModelRef as parseVideoGenerationModelRef } from "../../packages/media-generation-core/src/model-ref.js"; // Sanctioned domain alias. diff --git a/src/plugin-sdk/command-status.runtime.test.ts b/src/plugin-sdk/command-status.runtime.test.ts index 519ecd7544fc..f12326c72132 100644 --- a/src/plugin-sdk/command-status.runtime.test.ts +++ b/src/plugin-sdk/command-status.runtime.test.ts @@ -17,7 +17,7 @@ vi.mock("../auto-reply/reply/commands-status.js", () => ({ })); vi.mock("../gateway/session-utils.js", () => ({ - loadSessionEntryReadOnly: loadSessionEntry, + loadGatewaySessionEntryReadOnly: loadSessionEntry, })); vi.mock("../agents/agent-scope.js", () => ({ diff --git a/src/plugin-sdk/command-status.runtime.ts b/src/plugin-sdk/command-status.runtime.ts index 257c8c739c80..f434f972c3a9 100644 --- a/src/plugin-sdk/command-status.runtime.ts +++ b/src/plugin-sdk/command-status.runtime.ts @@ -8,7 +8,7 @@ import { resolveCurrentDirectiveLevels } from "../auto-reply/reply/directive-han import { createModelSelectionState } from "../auto-reply/reply/model-selection.js"; import type { ReplyPayload } from "../auto-reply/types.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; -import { loadSessionEntryReadOnly } from "../gateway/session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../gateway/session-utils.js"; /** Inputs for rendering direct-session status replies outside the active channel turn. */ export type ResolveDirectStatusReplyForSessionParams = { @@ -43,7 +43,7 @@ export async function resolveDirectStatusReplyForSessionCore( return undefined; } - const statusLoaded = loadSessionEntryReadOnly(requestedSessionKey); + const statusLoaded = loadGatewaySessionEntryReadOnly(requestedSessionKey); const statusCfg = statusLoaded.cfg ?? params.cfg; const statusSessionKey = statusLoaded.canonicalKey; const statusEntry = statusLoaded.entry; diff --git a/src/transcripts/provider-registry.ts b/src/transcripts/provider-registry.ts index 23e1198991ae..d6b6cb32211f 100644 --- a/src/transcripts/provider-registry.ts +++ b/src/transcripts/provider-registry.ts @@ -1,5 +1,5 @@ import { createMediaProviderRegistry } from "../media-generation/provider-registry.js"; -export { normalizeCapabilityProviderId as normalizeTranscriptSourceProviderId } from "../plugins/provider-registry-shared.js"; +export { normalizeCapabilityProviderId as normalizeTranscriptSourceProviderId } from "../plugins/provider-registry-shared.js"; // Sanctioned domain alias. /** Transcript providers use targeted lookup to avoid broad capability discovery. */ export const { diff --git a/src/tui/embedded-backend.test.ts b/src/tui/embedded-backend.test.ts index 15acce40750e..2dc3c5b90ade 100644 --- a/src/tui/embedded-backend.test.ts +++ b/src/tui/embedded-backend.test.ts @@ -232,7 +232,7 @@ vi.mock("../gateway/session-utils.js", () => ({ loadCombinedSessionStoreForGatewayMock(...args), loadSessionEntry: (sessionKey: string, opts?: { agentId?: string }) => loadSessionEntryMock(sessionKey, opts), - loadSessionEntryReadOnly: (sessionKey: string, opts?: { agentId?: string }) => + loadGatewaySessionEntryReadOnly: (sessionKey: string, opts?: { agentId?: string }) => loadSessionEntryMock(sessionKey, opts), resolveCanonicalGatewaySessionStoreKey: ({ key }: { key: string }) => ({ primaryKey: key, diff --git a/src/tui/embedded-backend.ts b/src/tui/embedded-backend.ts index 42babba3c00a..7acaf4248152 100644 --- a/src/tui/embedded-backend.ts +++ b/src/tui/embedded-backend.ts @@ -75,7 +75,7 @@ import { listSessionsFromStoreAsync, loadCombinedSessionStoreForGatewayCore, loadSessionEntry, - loadSessionEntryReadOnly, + loadGatewaySessionEntryReadOnly, resolveCanonicalGatewaySessionStoreKey, resolveGatewaySessionStoreTargetWithStore, resolveSessionModelRef, @@ -627,7 +627,7 @@ export class EmbeddedTuiBackend implements TuiBackend { async loadHistory(opts: { sessionKey: string; agentId?: string; limit?: number }) { await this.ready; const loadOptions = opts.agentId ? { agentId: opts.agentId } : undefined; - const { cfg, storePath, store, entry, canonicalKey } = loadSessionEntryReadOnly( + const { cfg, storePath, store, entry, canonicalKey } = loadGatewaySessionEntryReadOnly( opts.sessionKey, { ...loadOptions, includeStoreChildEntries: true }, ); @@ -807,7 +807,7 @@ export class EmbeddedTuiBackend implements TuiBackend { async resetSession(key: string, reason?: "new" | "reset", opts?: { agentId?: string }) { await this.ready; - if (loadSessionEntryReadOnly(key, opts).entry?.incognito === true) { + if (loadGatewaySessionEntryReadOnly(key, opts).entry?.incognito === true) { throw new Error("Incognito sessions cannot reset in place."); } const result = await performGatewaySessionReset({ diff --git a/test/e2e/qa-lab/runtime/gateway-usage-memory-apis.e2e.test.ts b/test/e2e/qa-lab/runtime/gateway-usage-memory-apis.e2e.test.ts index af32eb9bc65b..e0a71eb10aa7 100644 --- a/test/e2e/qa-lab/runtime/gateway-usage-memory-apis.e2e.test.ts +++ b/test/e2e/qa-lab/runtime/gateway-usage-memory-apis.e2e.test.ts @@ -15,7 +15,7 @@ import { READ_SCOPE } from "../../../../src/gateway/method-scopes.js"; import { clearModelAuthStatusUsageCache } from "../../../../src/gateway/server-methods/models-auth-status-usage-cache.js"; import { testApi as usageTestApi } from "../../../../src/gateway/server-methods/usage.js"; import { startGatewayServer } from "../../../../src/gateway/server.js"; -import { loadSessionEntryReadOnly } from "../../../../src/gateway/session-utils.js"; +import { loadGatewaySessionEntryReadOnly } from "../../../../src/gateway/session-utils.js"; import { connectGatewayClient, disconnectGatewayClient, @@ -204,7 +204,7 @@ describe("gateway usage and memory APIs", () => { sessionId: FIXTURE_SESSION_ID, storePath: databasePath, }); - const storedSession = loadSessionEntryReadOnly(FIXTURE_SESSION_KEY); + const storedSession = loadGatewaySessionEntryReadOnly(FIXTURE_SESSION_KEY); expect(storedSession).toMatchObject({ entry: { sessionId: FIXTURE_SESSION_ID, diff --git a/test/scripts/changed-path-facts.test.ts b/test/scripts/changed-path-facts.test.ts index d8dfd89d14a8..de19ff1c64bf 100644 --- a/test/scripts/changed-path-facts.test.ts +++ b/test/scripts/changed-path-facts.test.ts @@ -41,6 +41,12 @@ describe("changed path facts", () => { isTestOnly: true, isNativeOnly: false, }); + expect(getChangedPathFacts("src/gateway/server.auth.control-ui.suite.ts")).toMatchObject({ + surface: "source", + isChangedLaneTest: true, + isTestOnly: true, + isNativeOnly: false, + }); expect(getChangedPathFacts("apps/shared/OpenClawKit/Sources/Foo.swift")).toMatchObject({ surface: "app", isChangedLaneTest: false, diff --git a/test/scripts/ci-changed-node-test-plan.test.ts b/test/scripts/ci-changed-node-test-plan.test.ts index 7acdc9084cf5..efbe456b9b20 100644 --- a/test/scripts/ci-changed-node-test-plan.test.ts +++ b/test/scripts/ci-changed-node-test-plan.test.ts @@ -78,6 +78,9 @@ describe("CI changed Node test plan", () => { expect(hasBuildArtifactAffectingChange(["src/agents/foo.test.ts", "test/helpers/x.ts"])).toBe( false, ); + expect(hasBuildArtifactAffectingChange(["src/gateway/server.auth.control-ui.suite.ts"])).toBe( + false, + ); expect(hasBuildArtifactAffectingChange(["src/agents/foo.ts"])).toBe(true); // Build-input classification: only sources and the build pipeline can // change dist bytes; repo scripts, workflows, and qa scenarios cannot. diff --git a/test/scripts/oxlint-config.test.ts b/test/scripts/oxlint-config.test.ts index 6b37f5e5fad2..fd89bc9778a2 100644 --- a/test/scripts/oxlint-config.test.ts +++ b/test/scripts/oxlint-config.test.ts @@ -210,8 +210,8 @@ describe("oxlint config", () => { }, { files: [ - "**/*.test.ts", - "**/*.test.tsx", + "**/*.{test,suite}.ts", + "**/*.{test,suite}.tsx", "**/*.e2e.test.ts", "**/*.live.test.ts", "**/*test-harness.ts", @@ -246,6 +246,17 @@ describe("oxlint config", () => { expect(override.excludeFiles).toContain("ui/src/i18n/locales/**"); expect(override.excludeFiles).toContain("src/wizard/i18n/locales/**"); } + for (const override of scopedBudgets.slice(0, 3)) { + expect(override.excludeFiles).toContain("**/*.{test,spec,suite}.*"); + } + expect(scopedBudgets[3]?.files).toEqual( + expect.arrayContaining([ + "src/**/*.{test,spec,suite}.*", + "ui/src/**/*.{test,spec,suite}.*", + "packages/**/*.{test,spec,suite}.*", + "extensions/**/*.{test,spec,suite}.*", + ]), + ); expect(exactExceptions).toEqual([ { files: ["extensions/copilot/src/event-bridge.ts"], From 35d764076e09a8d7f9c4e2c3495eb213415e69db Mon Sep 17 00:00:00 2001 From: Josh Avant <830519+joshavant@users.noreply.github.com> Date: Tue, 11 Aug 2026 23:19:17 -0500 Subject: [PATCH 008/165] fix(audit): ignore inherited execution identity evidence (#122418) * fix(audit): require owned admission data * docs(agents): preserve owned admission invariant --- AGENTS.md | 2 +- src/audit/audit-event-writer.test.ts | 192 ++++++-- .../execution-identity-admission.test.ts | 455 ++++++++++++++++++ src/audit/execution-identity-admission.ts | 245 +++++----- 4 files changed, 753 insertions(+), 141 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d6780fca92ed..ce6f603f0d95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -172,7 +172,7 @@ Skills own workflows; root owns hard policy and routing. Product direction and m - Execution identity is opt-in diagnostic provenance, never authorization or enforcement. Unknown facts stay unknown; record ingress or invoker facts only at their authoritative producer. Never infer identity from session keys, `runId`, or routing metadata. - Invoker evidence is tri-state: tagged principal-bearing input is `present`, tagged principal-less input is `unknown`, and omission alone is `absent`. Validate the closed raw variant before projection or field dropping; reject malformed, mixed, untagged, or extra-field input instead of normalizing it to `unknown` or absence. - Each outer admitted turn owns one immutable `executionId` and `contextId`; `runId` is non-unique correlation. Retries, fallbacks, and recovery reuse the original admission identity. Only byte-identical canonical replay is idempotent. -- Admission may only validate, bound, freeze, and enqueue through the shared audit writer. No synchronous SQLite, schema, filesystem, HMAC-key, or readiness work. Audit failure never delays or aborts execution. +- Admission may only validate, bound, freeze, and enqueue through the shared audit writer. Admission validates only a recursively owned, enumerable, accessor-free data snapshot constructed from descriptors before schema checks or ordinary property reads; inherited properties are absent and accessors never run. No synchronous SQLite, schema, filesystem, HMAC-key, or readiness work. Audit failure never delays or aborts execution. - Raw identity references are transient worker-message data. Never persist, export, inspect, or log them. Public Plugin SDK ingress must strip private recovery/admission authority, including JavaScript extra and inherited properties. - Default or disabled collection creates and propagates no identity token and does not create optional storage. Existing-storage maintenance may continue. Reads enforce expiry before projection; missing or expired evidence never proves no run occurred. - `audit.run.inspect` intentionally uses `operator.read` within one trusted Gateway domain. Reader isolation requires separate domains. Ask before changing this scope, default-off behavior, retained fields, 30-day cutoff, maintenance/row bounds, or schema/protocol contract. diff --git a/src/audit/audit-event-writer.test.ts b/src/audit/audit-event-writer.test.ts index b811c80313ed..586476ee05b5 100644 --- a/src/audit/audit-event-writer.test.ts +++ b/src/audit/audit-event-writer.test.ts @@ -19,6 +19,11 @@ import { processExecutionIdentityAdmissionWork, } from "./execution-identity-context.js"; +function defineObjectPrototypeProperties(descriptors: PropertyDescriptorMap): void { + // oxlint-disable-next-line no-extend-native -- Exercise hostile prototype pollution across the real worker boundary. + Object.defineProperties(Object.prototype, descriptors); +} + function captureExecutionIdentityAdmissionEnvelope( facts: ExecutionIdentityAdmissionFacts, options: { @@ -229,45 +234,151 @@ describe("audit event worker", () => { } }); - it("preserves explicit unknown invoker evidence through the worker clone boundary", async () => { + it("persists owned unknown and omits inherited evidence through the worker clone boundary", async () => { const stateDir = tempDirs.make("openclaw-audit-writer-"); const database = { env: { OPENCLAW_STATE_DIR: stateDir } }; const errors: string[] = []; const writer = createAuditEventWriter({ stateDir, onError: (error) => errors.push(error) }); const clearSink = configureExecutionIdentityAdmissionSink(writer.recordExecutionIdentity); const admittedAt = Date.now(); - - expect( - enqueueExecutionIdentityContextAtAdmission( - { - runId: "unknown-invoker-run", - agentId: "main", - ingress: { kind: "local-cli", boundary: "agent-command.local", state: "present" }, - runtime: { kind: "embedded" }, - invoker: { state: "unknown" }, - }, - { - enabled: true, - contextId: "unknown-invoker-context", - executionId: "unknown-invoker-execution", - now: admittedAt, - runtimeInstanceId: "private-runtime-reference", - }, - ), - ).toEqual({ - candidateContextId: "unknown-invoker-context", - candidateExecutionId: "unknown-invoker-execution", - accepted: true, - }); - clearSink(); - await writer.stop(); - - const inspected = inspectExecutionIdentityRun( - { executionId: "unknown-invoker-execution" }, - { ...database, now: admittedAt }, + const inheritedRefs = { + invoker: "raw-inherited-principal", + applicableGrants: "raw-inherited-grant", + assurance: "raw-inherited-assurance", + rawSourceRef: "raw-inherited-source", + } as const; + const prior = new Map( + Object.keys(inheritedRefs).map((key) => [ + key, + Object.getOwnPropertyDescriptor(Object.prototype, key), + ]), ); + let inheritedInvokerReads = 0; + + try { + try { + defineObjectPrototypeProperties({ + invoker: { + configurable: true, + enumerable: false, + get: () => { + inheritedInvokerReads += 1; + return { + state: "present", + kind: "local-account", + rawPrincipalRef: inheritedRefs.invoker, + }; + }, + }, + applicableGrants: { + configurable: true, + enumerable: false, + value: [{ rawGrantRef: inheritedRefs.applicableGrants, state: "present" }], + }, + assurance: { + configurable: true, + enumerable: false, + value: [ + { + kind: "other", + rawEvidenceRef: inheritedRefs.assurance, + strength: "self-asserted", + }, + ], + }, + rawSourceRef: { + configurable: true, + enumerable: false, + value: inheritedRefs.rawSourceRef, + }, + }); + expect( + enqueueExecutionIdentityContextAtAdmission( + { + runId: "absent-invoker-run", + agentId: "main", + ingress: { + kind: "local-cli", + boundary: "agent-command.local", + state: "present", + }, + runtime: { kind: "embedded" }, + }, + { + enabled: true, + contextId: "absent-invoker-context", + executionId: "absent-invoker-execution", + now: admittedAt, + runtimeInstanceId: "private-absent-runtime-reference", + }, + ), + ).toEqual({ + candidateContextId: "absent-invoker-context", + candidateExecutionId: "absent-invoker-execution", + accepted: true, + }); + } finally { + for (const [key, descriptor] of prior) { + if (descriptor) { + defineObjectPrototypeProperties({ [key]: descriptor }); + } else { + delete (Object.prototype as Record)[key]; + } + } + } + + expect( + enqueueExecutionIdentityContextAtAdmission( + { + runId: "unknown-invoker-run", + agentId: "main", + ingress: { kind: "local-cli", boundary: "agent-command.local", state: "present" }, + runtime: { kind: "embedded" }, + invoker: { state: "unknown" }, + }, + { + enabled: true, + contextId: "unknown-invoker-context", + executionId: "unknown-invoker-execution", + now: admittedAt + 1, + runtimeInstanceId: "private-unknown-runtime-reference", + }, + ), + ).toEqual({ + candidateContextId: "unknown-invoker-context", + candidateExecutionId: "unknown-invoker-execution", + accepted: true, + }); + } finally { + clearSink(); + await writer.stop(); + } + + const absentInspection = inspectExecutionIdentityRun( + { executionId: "absent-invoker-execution" }, + { ...database, now: admittedAt + 1 }, + ); + const unknownInspection = inspectExecutionIdentityRun( + { executionId: "unknown-invoker-execution" }, + { ...database, now: admittedAt + 1 }, + ); + expect(inheritedInvokerReads).toBe(0); expect(errors).toEqual([]); - expect(inspected).toMatchObject({ + expect(absentInspection).toMatchObject({ + identity: { + state: "present", + context: { + invoker: { state: "absent" }, + ingress: { state: "present" }, + applicableGrants: [], + assurance: [{ kind: "runtime-binding", strength: "boundary-verified" }], + coverageState: "unattributed", + missingEvidence: ["invoker.principal"], + }, + }, + coverage: { state: "unattributed", missingEvidence: ["invoker.principal"] }, + }); + expect(unknownInspection).toMatchObject({ identity: { state: "present", context: { @@ -278,7 +389,24 @@ describe("audit event worker", () => { }, coverage: { state: "unknown", missingEvidence: ["invoker.principal"] }, }); - expect(JSON.stringify(inspected)).not.toContain("private-runtime-reference"); + const persisted = openOpenClawStateDatabase(database) + .db.prepare( + "SELECT context_json FROM execution_identity_contexts WHERE execution_id IN (?, ?) ORDER BY execution_id", + ) + .all("absent-invoker-execution", "unknown-invoker-execution") as Array<{ + context_json: string; + }>; + const publicAndStored = JSON.stringify({ + errors, + absentInspection, + unknownInspection, + persisted, + }); + for (const rawRef of Object.values(inheritedRefs)) { + expect(publicAndStored).not.toContain(rawRef); + } + expect(publicAndStored).not.toContain("private-absent-runtime-reference"); + expect(publicAndStored).not.toContain("private-unknown-runtime-reference"); }); it("prunes expired identity contexts before preserving exact-envelope conflicts", async () => { diff --git a/src/audit/execution-identity-admission.test.ts b/src/audit/execution-identity-admission.test.ts index 62b15df291bd..662be64231a8 100644 --- a/src/audit/execution-identity-admission.test.ts +++ b/src/audit/execution-identity-admission.test.ts @@ -5,6 +5,7 @@ import { enqueueExecutionIdentityContextAtAdmission, hasExecutionIdentityAdmissionSink, parseExecutionIdentityAdmissionEnvelope, + parseExecutionIdentityAdmissionWork, type ExecutionIdentityAdmissionEnvelope, type ExecutionIdentityAdmissionFacts, type ExecutionIdentityAdmissionWork, @@ -13,6 +14,22 @@ import { const ADMISSION_MAX_BYTES = 16 * 1024; const ADMISSION_MAX_ITEMS = 16; +function defineObjectPrototypeProperty(key: string, descriptor: PropertyDescriptor): void { + // oxlint-disable-next-line no-extend-native -- Exercise hostile prototype pollution at the admission boundary. + Object.defineProperty(Object.prototype, key, descriptor); +} + +function restoreObjectPrototypeProperty( + key: string, + descriptor: PropertyDescriptor | undefined, +): void { + if (descriptor) { + defineObjectPrototypeProperty(key, descriptor); + } else { + delete (Object.prototype as Record)[key]; + } +} + function facts(overrides: Partial = {}) { return { runId: "run-1", @@ -150,6 +167,379 @@ describe("execution identity admission envelope", () => { } }); + it("omits inherited outer evidence instead of projecting it", () => { + const inheritedRefs = { + invoker: { state: "unknown" }, + applicableGrants: [{ rawGrantRef: "inherited-grant", state: "present" }], + assurance: [ + { + kind: "other", + rawEvidenceRef: "inherited-assurance", + strength: "self-asserted", + }, + ], + } as const; + const prior = new Map( + Object.keys(inheritedRefs).map((key) => [ + key, + Object.getOwnPropertyDescriptor(Object.prototype, key), + ]), + ); + let envelope: ExecutionIdentityAdmissionEnvelope; + try { + for (const [key, value] of Object.entries(inheritedRefs)) { + defineObjectPrototypeProperty(key, { + configurable: true, + enumerable: false, + value, + writable: true, + }); + } + envelope = captureEnvelope(facts(), { + contextId: "context-inherited", + executionId: "execution-inherited", + now: 1, + runtimeInstanceId: "runtime-owned", + }); + } finally { + for (const [key, descriptor] of prior) { + restoreObjectPrototypeProperty(key, descriptor); + } + } + + expect(Object.hasOwn(envelope!, "invoker")).toBe(false); + expect(envelope!.applicableGrants).toEqual([]); + expect(envelope!.assurance).toEqual([ + { + kind: "runtime-binding", + rawEvidenceRef: "runtime-owned", + strength: "boundary-verified", + }, + ]); + }); + + it("never reads inherited accessors while treating optional evidence as omitted", () => { + const keys = ["invoker", "applicableGrants", "assurance"] as const; + const prior = new Map( + keys.map((key) => [key, Object.getOwnPropertyDescriptor(Object.prototype, key)]), + ); + const getterReads = new Map(keys.map((key) => [key, 0])); + let envelope: ExecutionIdentityAdmissionEnvelope; + try { + for (const key of keys) { + defineObjectPrototypeProperty(key, { + configurable: true, + enumerable: false, + get: () => { + getterReads.set(key, getterReads.get(key)! + 1); + return key === "invoker" + ? { state: "unknown" } + : key === "applicableGrants" + ? [{ rawGrantRef: "inherited-grant", state: "present" }] + : [ + { + kind: "other", + rawEvidenceRef: "inherited-assurance", + strength: "self-asserted", + }, + ]; + }, + }); + } + envelope = captureEnvelope(facts(), { + contextId: "context-inherited-getter", + executionId: "execution-inherited-getter", + now: 1, + runtimeInstanceId: "runtime-owned", + }); + } finally { + for (const [key, descriptor] of prior) { + restoreObjectPrototypeProperty(key, descriptor); + } + } + + expect(Object.fromEntries(getterReads)).toEqual({ + invoker: 0, + applicableGrants: 0, + assurance: 0, + }); + expect(Object.hasOwn(envelope!, "invoker")).toBe(false); + expect(envelope!.applicableGrants).toEqual([]); + expect(envelope!.assurance).toEqual([ + { + kind: "runtime-binding", + rawEvidenceRef: "runtime-owned", + strength: "boundary-verified", + }, + ]); + }); + + it.each([ + { + name: "ingress state", + key: "state", + value: "unknown", + admissionFacts: () => facts(), + assertOmitted: (envelope: ExecutionIdentityAdmissionEnvelope) => { + expect(envelope.ingress.state).toBe("present"); + }, + }, + { + name: "ingress source", + key: "rawSourceRef", + value: "inherited-source", + admissionFacts: () => facts(), + assertOmitted: (envelope: ExecutionIdentityAdmissionEnvelope) => { + expect(Object.hasOwn(envelope.ingress, "rawSourceRef")).toBe(false); + }, + }, + { + name: "invoker label", + key: "displayLabel", + value: "inherited-label", + admissionFacts: () => + facts({ + invoker: { + state: "present", + kind: "local-account", + rawPrincipalRef: "owned-principal", + }, + }), + assertOmitted: (envelope: ExecutionIdentityAdmissionEnvelope) => { + expect(envelope.invoker?.state).toBe("present"); + expect(Object.hasOwn(envelope.invoker!, "displayLabel")).toBe(false); + }, + }, + ])("omits inherited optional $name data", ({ key, value, admissionFacts, assertOmitted }) => { + const prior = Object.getOwnPropertyDescriptor(Object.prototype, key); + let dataEnvelope: ExecutionIdentityAdmissionEnvelope; + let getterEnvelope: ExecutionIdentityAdmissionEnvelope; + let getterReads = 0; + try { + defineObjectPrototypeProperty(key, { + configurable: true, + enumerable: false, + value, + writable: true, + }); + dataEnvelope = captureEnvelope(admissionFacts(), { + contextId: `context-${key}`, + executionId: `execution-${key}`, + now: 1, + runtimeInstanceId: "runtime-owned", + }); + defineObjectPrototypeProperty(key, { + configurable: true, + enumerable: false, + get: () => { + getterReads += 1; + return value; + }, + }); + getterEnvelope = captureEnvelope(admissionFacts(), { + contextId: `context-${key}-getter`, + executionId: `execution-${key}-getter`, + now: 2, + runtimeInstanceId: "runtime-owned", + }); + } finally { + restoreObjectPrototypeProperty(key, prior); + } + expect(getterReads).toBe(0); + assertOmitted(dataEnvelope!); + assertOmitted(getterEnvelope!); + }); + + it.each([ + ["outer run id", "runId", "inherited-run", () => omitOwn(facts(), "runId")], + ["outer agent id", "agentId", "inherited-agent", () => omitOwn(facts(), "agentId")], + ["outer ingress", "ingress", facts().ingress, () => omitOwn(facts(), "ingress")], + ["outer runtime", "runtime", facts().runtime, () => omitOwn(facts(), "runtime")], + [ + "ingress kind", + "kind", + "local-cli", + () => facts({ ingress: { boundary: "agent-command.local" } as never }), + ], + [ + "ingress boundary", + "boundary", + "agent-command.local", + () => facts({ ingress: { kind: "local-cli" } as never }), + ], + ["invoker state", "state", "unknown", () => facts({ invoker: {} as never })], + [ + "invoker kind", + "kind", + "local-account", + () => facts({ invoker: { state: "present", rawPrincipalRef: "owned" } as never }), + ], + [ + "invoker principal", + "rawPrincipalRef", + "inherited-principal", + () => facts({ invoker: { state: "present", kind: "local-account" } as never }), + ], + [ + "grant reference", + "rawGrantRef", + "inherited-grant", + () => facts({ applicableGrants: [{ state: "present" } as never] }), + ], + [ + "grant state", + "state", + "present", + () => facts({ applicableGrants: [{ rawGrantRef: "owned-grant" } as never] }), + ], + [ + "assurance kind", + "kind", + "other", + () => + facts({ + assurance: [{ rawEvidenceRef: "owned-evidence", strength: "self-asserted" } as never], + }), + ], + [ + "assurance reference", + "rawEvidenceRef", + "inherited-evidence", + () => facts({ assurance: [{ kind: "other", strength: "self-asserted" } as never] }), + ], + [ + "assurance strength", + "strength", + "self-asserted", + () => facts({ assurance: [{ kind: "other", rawEvidenceRef: "owned-evidence" } as never] }), + ], + ] as const)( + "rejects inherited required $0 before allocation and enqueue", + (_name, key, inheritedValue, admissionFacts) => { + const prior = Object.getOwnPropertyDescriptor(Object.prototype, key); + let inheritedReads = 0; + let allocationReads = 0; + const sink = vi.fn(() => true); + const clear = configureExecutionIdentityAdmissionSink(sink); + try { + defineObjectPrototypeProperty(key, { + configurable: true, + enumerable: false, + get: () => { + inheritedReads += 1; + return inheritedValue; + }, + }); + const options = { enabled: true, runtimeInstanceId: "runtime-owned" }; + Object.defineProperty(options, "contextId", { + enumerable: true, + get: () => { + allocationReads += 1; + return "must-not-allocate"; + }, + }); + expect( + enqueueExecutionIdentityContextAtAdmission(admissionFacts() as never, options), + ).toBeUndefined(); + } finally { + clear(); + restoreObjectPrototypeProperty(key, prior); + } + expect(inheritedReads).toBe(0); + expect(allocationReads).toBe(0); + expect(sink).not.toHaveBeenCalled(); + }, + ); + + it.each([ + { + name: "outer ingress", + prepare: () => { + const admissionFacts = facts(); + return { admissionFacts, target: admissionFacts, key: "ingress" }; + }, + }, + ...["invoker", "applicableGrants", "assurance"].map((key) => ({ + name: `outer ${key}`, + prepare: () => { + const admissionFacts = facts(); + return { admissionFacts, target: admissionFacts, key }; + }, + })), + ...["kind", "boundary", "state", "rawSourceRef"].map((key) => ({ + name: `ingress ${key}`, + prepare: () => { + const admissionFacts = facts(); + return { admissionFacts, target: admissionFacts.ingress, key }; + }, + })), + ...["state", "kind", "rawPrincipalRef", "displayLabel"].map((key) => ({ + name: `invoker ${key}`, + prepare: () => { + const invoker = { + state: "present" as const, + kind: "local-account" as const, + rawPrincipalRef: "owned-principal", + displayLabel: "owned-label", + }; + const admissionFacts = facts({ invoker }); + return { admissionFacts, target: invoker, key }; + }, + })), + ...["rawGrantRef", "state"].map((key) => ({ + name: `grant ${key}`, + prepare: () => { + const grant = { rawGrantRef: "owned-grant", state: "present" as const }; + const admissionFacts = facts({ applicableGrants: [grant] }); + return { admissionFacts, target: grant, key }; + }, + })), + ...["kind", "rawEvidenceRef", "strength"].map((key) => ({ + name: `assurance ${key}`, + prepare: () => { + const assurance = { + kind: "other" as const, + rawEvidenceRef: "owned-evidence", + strength: "self-asserted" as const, + }; + const admissionFacts = facts({ assurance: [assurance] }); + return { admissionFacts, target: assurance, key }; + }, + })), + ])("rejects an own accessor at $name without reading it or allocating", ({ prepare }) => { + const { admissionFacts, target, key } = prepare(); + let accessorReads = 0; + let allocationReads = 0; + Object.defineProperty(target, key, { + configurable: true, + enumerable: true, + get: () => { + accessorReads += 1; + return "must-not-read"; + }, + }); + const options = { enabled: true, runtimeInstanceId: "runtime-owned" }; + Object.defineProperty(options, "contextId", { + enumerable: true, + get: () => { + allocationReads += 1; + return "must-not-allocate"; + }, + }); + const sink = vi.fn(() => true); + const clear = configureExecutionIdentityAdmissionSink(sink); + try { + expect( + enqueueExecutionIdentityContextAtAdmission(admissionFacts as never, options), + ).toBeUndefined(); + } finally { + clear(); + } + expect(accessorReads).toBe(0); + expect(allocationReads).toBe(0); + expect(sink).not.toHaveBeenCalled(); + }); + it("rejects malformed, ambiguous, oversized, and noncanonical invoker variants", () => { const present = captureEnvelope( facts({ @@ -271,6 +661,65 @@ describe("execution identity admission envelope", () => { expect(accessorReads).toBe(0); }); + it("revalidates envelopes and worker messages from owned data only", () => { + const envelope = captureEnvelope(facts(), { + contextId: "context-revalidation", + executionId: "execution-revalidation", + now: 1, + runtimeInstanceId: "runtime-owned", + }); + const priorInvoker = Object.getOwnPropertyDescriptor(Object.prototype, "invoker"); + const priorIngress = Object.getOwnPropertyDescriptor(Object.prototype, "ingress"); + const priorKind = Object.getOwnPropertyDescriptor(Object.prototype, "kind"); + let inheritedReads = 0; + let parsed: ExecutionIdentityAdmissionEnvelope; + try { + defineObjectPrototypeProperty("invoker", { + configurable: true, + enumerable: false, + get: () => { + inheritedReads += 1; + return { state: "unknown" }; + }, + }); + parsed = parseExecutionIdentityAdmissionEnvelope(envelope); + + defineObjectPrototypeProperty("ingress", { + configurable: true, + enumerable: false, + get: () => { + inheritedReads += 1; + return envelope.ingress; + }, + }); + expect(() => parseExecutionIdentityAdmissionEnvelope(omitOwn(envelope, "ingress"))).toThrow( + "execution identity admission envelope violates its bounded contract", + ); + + defineObjectPrototypeProperty("kind", { + configurable: true, + enumerable: false, + get: () => { + inheritedReads += 1; + return "capture"; + }, + }); + expect(() => parseExecutionIdentityAdmissionWork({ envelope } as never)).toThrow( + "execution identity admission work violates its bounded contract", + ); + } finally { + for (const [key, descriptor] of [ + ["invoker", priorInvoker], + ["ingress", priorIngress], + ["kind", priorKind], + ] as const) { + restoreObjectPrototypeProperty(key, descriptor); + } + } + expect(inheritedReads).toBe(0); + expect(Object.hasOwn(parsed!, "invoker")).toBe(false); + }); + it("rejects invalid owned facts, excess items, and oversized encoded envelopes", () => { expect(() => captureEnvelope(facts({ runId: "" }), { @@ -394,3 +843,9 @@ describe("execution identity admission envelope", () => { expect(JSON.stringify(work.mock.calls)).not.toContain("raw-private-reference"); }); }); + +function omitOwn(value: T, key: K): Omit { + const copy = { ...value }; + delete copy[key]; + return copy; +} diff --git a/src/audit/execution-identity-admission.ts b/src/audit/execution-identity-admission.ts index 1f437ccd5b95..910f8980752a 100644 --- a/src/audit/execution-identity-admission.ts +++ b/src/audit/execution-identity-admission.ts @@ -25,6 +25,58 @@ const evidenceState = () => const closedObject = [0]>(properties: T) => Type.Object(properties, { additionalProperties: false }); +const ingressKind = () => + Type.Union([ + Type.Literal("local-cli"), + Type.Literal("gateway-client"), + Type.Literal("channel"), + Type.Literal("api"), + Type.Literal("schedule"), + Type.Literal("webhook"), + Type.Literal("task"), + Type.Literal("subagent"), + Type.Literal("acp"), + Type.Literal("worker"), + Type.Literal("plugin"), + Type.Literal("recovery"), + Type.Literal("system"), + ]); +const runtimeKind = () => + Type.Union([ + Type.Literal("gateway"), + Type.Literal("embedded"), + Type.Literal("worker"), + Type.Literal("plugin-harness"), + Type.Literal("acp"), + ]); +const admissionGrant = () => closedObject({ rawGrantRef: rawRef(), state: evidenceState() }); +const admissionGrants = () => + Type.Array(admissionGrant(), { maxItems: EXECUTION_IDENTITY_ADMISSION_MAX_ITEMS }); +const admissionAssurance = () => + Type.Array( + closedObject({ + kind: Type.Union([ + Type.Literal("durable-profile"), + Type.Literal("trusted-proxy"), + Type.Literal("tailscale-whois"), + Type.Literal("device-proof"), + Type.Literal("channel-admission"), + Type.Literal("local-process"), + Type.Literal("spawn-lineage"), + Type.Literal("worker-admission"), + Type.Literal("runtime-binding"), + Type.Literal("other"), + ]), + rawEvidenceRef: rawRef(), + strength: Type.Union([ + Type.Literal("self-asserted"), + Type.Literal("boundary-verified"), + Type.Literal("cryptographic"), + ]), + }), + { maxItems: EXECUTION_IDENTITY_ADMISSION_MAX_ITEMS }, + ); + const ExecutionIdentityAdmissionInvokerSchema = Type.Union([ closedObject({ state: Type.Literal("present"), @@ -53,61 +105,32 @@ const ExecutionIdentityAdmissionEnvelopeSchema = closedObject({ runtimeInstanceId: rawRef(), agentId: boundedRef(), ingress: closedObject({ - kind: Type.Union([ - Type.Literal("local-cli"), - Type.Literal("gateway-client"), - Type.Literal("channel"), - Type.Literal("api"), - Type.Literal("schedule"), - Type.Literal("webhook"), - Type.Literal("task"), - Type.Literal("subagent"), - Type.Literal("acp"), - Type.Literal("worker"), - Type.Literal("plugin"), - Type.Literal("recovery"), - Type.Literal("system"), - ]), + kind: ingressKind(), boundary: boundedRef(), state: evidenceState(), rawSourceRef: Type.Optional(rawRef()), }), runtime: closedObject({ - kind: Type.Union([ - Type.Literal("gateway"), - Type.Literal("embedded"), - Type.Literal("worker"), - Type.Literal("plugin-harness"), - Type.Literal("acp"), - ]), + kind: runtimeKind(), }), invoker: Type.Optional(ExecutionIdentityAdmissionInvokerSchema), - applicableGrants: Type.Array(closedObject({ rawGrantRef: rawRef(), state: evidenceState() }), { - maxItems: EXECUTION_IDENTITY_ADMISSION_MAX_ITEMS, + applicableGrants: admissionGrants(), + assurance: admissionAssurance(), +}); + +const ExecutionIdentityAdmissionFactsSchema = closedObject({ + runId: boundedRef(), + agentId: boundedRef(), + ingress: closedObject({ + kind: ingressKind(), + boundary: boundedRef(), + state: Type.Optional(evidenceState()), + rawSourceRef: Type.Optional(rawRef()), }), - assurance: Type.Array( - closedObject({ - kind: Type.Union([ - Type.Literal("durable-profile"), - Type.Literal("trusted-proxy"), - Type.Literal("tailscale-whois"), - Type.Literal("device-proof"), - Type.Literal("channel-admission"), - Type.Literal("local-process"), - Type.Literal("spawn-lineage"), - Type.Literal("worker-admission"), - Type.Literal("runtime-binding"), - Type.Literal("other"), - ]), - rawEvidenceRef: rawRef(), - strength: Type.Union([ - Type.Literal("self-asserted"), - Type.Literal("boundary-verified"), - Type.Literal("cryptographic"), - ]), - }), - { maxItems: EXECUTION_IDENTITY_ADMISSION_MAX_ITEMS }, - ), + runtime: closedObject({ kind: runtimeKind() }), + invoker: Type.Optional(ExecutionIdentityAdmissionInvokerSchema), + applicableGrants: Type.Optional(admissionGrants()), + assurance: Type.Optional(admissionAssurance()), }); const ExecutionIdentityAdmissionTokenSchema = closedObject({ @@ -166,9 +189,11 @@ function freezeEnvelope(value: T, seen = new WeakSet()): T { return Object.freeze(value); } -function assertPlainCloneData(value: unknown, ancestors = new WeakSet()): void { +// Snapshot descriptors before schema or projection: TypeBox accepts inherited +// keys, which would otherwise turn prototype data into diagnostic provenance. +function copyOwnedData(value: T, ancestors = new WeakSet()): T { if (value === null || ["string", "number", "boolean"].includes(typeof value)) { - return; + return value; } if (typeof value !== "object" || isProxy(value)) { throw new Error("execution identity admission data must be clone-safe plain data"); @@ -180,10 +205,15 @@ function assertPlainCloneData(value: unknown, ancestors = new WeakSet()) try { const prototype = Object.getPrototypeOf(value); const keys = Reflect.ownKeys(value); + const array = Array.isArray(value); if (Array.isArray(value)) { + const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length"); if ( prototype !== Array.prototype || - keys.length !== value.length + 1 || + !lengthDescriptor || + !("value" in lengthDescriptor) || + typeof lengthDescriptor.value !== "number" || + keys.length !== lengthDescriptor.value + 1 || keys.at(-1) !== "length" ) { throw new Error("execution identity admission data must be clone-safe plain data"); @@ -191,51 +221,63 @@ function assertPlainCloneData(value: unknown, ancestors = new WeakSet()) } else if (prototype !== Object.prototype && prototype !== null) { throw new Error("execution identity admission data must be clone-safe plain data"); } + const copy: unknown[] | Record = array ? [] : Object.create(null); for (const [index, key] of keys.entries()) { - if (key === "length" && Array.isArray(value)) { + if (key === "length" && array) { continue; } - if (typeof key !== "string" || (Array.isArray(value) && key !== String(index))) { + if (typeof key !== "string" || (array && key !== String(index))) { throw new Error("execution identity admission data must be clone-safe plain data"); } const descriptor = Object.getOwnPropertyDescriptor(value, key); if (!descriptor?.enumerable || !("value" in descriptor)) { throw new Error("execution identity admission data must be clone-safe plain data"); } - assertPlainCloneData(descriptor.value, ancestors); + Object.defineProperty(copy, key, { + configurable: true, + enumerable: true, + value: copyOwnedData(descriptor.value, ancestors), + writable: true, + }); } + return copy as T; } finally { ancestors.delete(value); } } -function validateEnvelope(value: unknown): asserts value is ExecutionIdentityAdmissionEnvelope { - assertPlainCloneData(value); +function validateEnvelope(value: unknown): ExecutionIdentityAdmissionEnvelope { + const owned = copyOwnedData(value); if ( - !Value.Check(ExecutionIdentityAdmissionEnvelopeSchema, value) || - !Number.isSafeInteger(value.createdAt) + !Value.Check(ExecutionIdentityAdmissionEnvelopeSchema, owned) || + !Number.isSafeInteger(owned.createdAt) ) { throw new Error("execution identity admission envelope violates its bounded contract"); } - const encoded = JSON.stringify(value); + const encoded = JSON.stringify(owned); if (Buffer.byteLength(encoded, "utf8") > EXECUTION_IDENTITY_ADMISSION_MAX_BYTES) { throw new Error("execution identity admission envelope exceeds 16 KiB"); } + return owned; } -function validateRawInvoker(value: unknown): void { - if (value !== undefined && !Value.Check(ExecutionIdentityAdmissionInvokerSchema, value)) { - throw new Error("execution identity admission invoker violates its bounded contract"); +function validateFacts(value: unknown): ExecutionIdentityAdmissionFacts { + const owned = copyOwnedData(value); + if (!Value.Check(ExecutionIdentityAdmissionFactsSchema, owned)) { + throw new Error("execution identity admission facts violate their bounded contract"); } + return owned; } -function validateToken(value: unknown): asserts value is ExecutionIdentityAdmissionToken { +function validateToken(value: unknown): ExecutionIdentityAdmissionToken { + const owned = copyOwnedData(value); if ( - !Value.Check(ExecutionIdentityAdmissionTokenSchema, value) || - !Number.isSafeInteger(value.createdAt) + !Value.Check(ExecutionIdentityAdmissionTokenSchema, owned) || + !Number.isSafeInteger(owned.createdAt) ) { throw new Error("execution identity admission token violates its bounded contract"); } + return owned; } /** Allocate the immutable correlation owned by one outer admitted turn. */ @@ -250,15 +292,13 @@ export function createExecutionIdentityAdmissionToken( runId, createdAt: options.now ?? Date.now(), }; - validateToken(token); - return freezeEnvelope(token); + return freezeEnvelope(validateToken(token)); } export function parseExecutionIdentityAdmissionToken( value: unknown, ): ExecutionIdentityAdmissionToken { - validateToken(value); - return freezeEnvelope({ ...value }); + return freezeEnvelope(validateToken(value)); } function redactDisplayLabel(value: string): string { @@ -274,22 +314,12 @@ function redactDisplayLabel(value: string): string { function captureExecutionIdentityAdmissionEnvelope( facts: ExecutionIdentityAdmissionFacts, options: { - contextId?: string; - executionId?: string; - now?: number; runtimeInstanceId?: string; - token?: ExecutionIdentityAdmissionToken; - } = {}, + token: ExecutionIdentityAdmissionToken; + }, ): ExecutionIdentityAdmissionEnvelope { - const token = - options.token ?? - createExecutionIdentityAdmissionToken(facts.runId, { - contextId: options.contextId, - executionId: options.executionId, - now: options.now, - }); - validateToken(token); - if (token.runId !== facts.runId) { + const ownedToken = validateToken(options.token); + if (ownedToken.runId !== facts.runId) { throw new Error("execution identity admission token disagrees with the admitted run"); } const runtimeInstanceId = options.runtimeInstanceId ?? PROCESS_RUNTIME_INSTANCE_ID; @@ -302,10 +332,10 @@ function captureExecutionIdentityAdmissionEnvelope( ]; const envelope = { envelopeVersion: 1 as const, - contextId: token.contextId, - executionId: token.executionId, - runId: token.runId, - createdAt: token.createdAt, + contextId: ownedToken.contextId, + executionId: ownedToken.executionId, + runId: ownedToken.runId, + createdAt: ownedToken.createdAt, runtimeInstanceId, agentId: facts.agentId, ingress: { ...facts.ingress, state: facts.ingress.state ?? "present" }, @@ -337,24 +367,23 @@ function captureExecutionIdentityAdmissionEnvelope( strength: item.strength, })), }; - validateEnvelope(envelope); - return freezeEnvelope(envelope); + return freezeEnvelope(validateEnvelope(envelope)); } /** Revalidate a structured-cloned worker message before any persistence work. */ export function parseExecutionIdentityAdmissionEnvelope( value: unknown, ): ExecutionIdentityAdmissionEnvelope { - validateEnvelope(value); - const parsed = captureExecutionIdentityAdmissionEnvelope(value, { - token: createExecutionIdentityAdmissionToken(value.runId, { - contextId: value.contextId, - executionId: value.executionId, - now: value.createdAt, + const envelope = validateEnvelope(value); + const parsed = captureExecutionIdentityAdmissionEnvelope(envelope, { + token: createExecutionIdentityAdmissionToken(envelope.runId, { + contextId: envelope.contextId, + executionId: envelope.executionId, + now: envelope.createdAt, }), - runtimeInstanceId: value.runtimeInstanceId, + runtimeInstanceId: envelope.runtimeInstanceId, }); - if (JSON.stringify(parsed) !== JSON.stringify(value)) { + if (JSON.stringify(parsed) !== JSON.stringify(envelope)) { throw new Error("execution identity admission envelope is not canonical"); } return parsed; @@ -364,10 +393,11 @@ export function parseExecutionIdentityAdmissionEnvelope( export function parseExecutionIdentityAdmissionWork( value: unknown, ): ExecutionIdentityAdmissionWork { - if (!value || typeof value !== "object") { + const owned = copyOwnedData(value); + if (!owned || typeof owned !== "object") { throw new Error("execution identity admission work violates its bounded contract"); } - const work = value as { kind?: unknown; envelope?: unknown; token?: unknown }; + const work = owned as { kind?: unknown; envelope?: unknown; token?: unknown }; if (work.kind === "capture") { return freezeEnvelope({ kind: "capture" as const, @@ -424,21 +454,20 @@ export function enqueueExecutionIdentityContextAtAdmission( return undefined; } try { - assertPlainCloneData(facts); - validateRawInvoker(facts.invoker); - const token = + const ownedFacts = validateFacts(facts); + const token = validateToken( options.token ?? - createExecutionIdentityAdmissionToken(facts.runId, { - contextId: options.contextId, - executionId: options.executionId, - now: options.now, - }); - validateToken(token); + createExecutionIdentityAdmissionToken(ownedFacts.runId, { + contextId: options.contextId, + executionId: options.executionId, + now: options.now, + }), + ); const work: ExecutionIdentityAdmissionWork = options.retryOnly ? { kind: "retry-reference", token } : { kind: "capture", - envelope: captureExecutionIdentityAdmissionEnvelope(facts, { + envelope: captureExecutionIdentityAdmissionEnvelope(ownedFacts, { token, runtimeInstanceId: options.runtimeInstanceId, }), From a89b88ec0ea756c48e2d28f246ac0f325e420c51 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:20:00 -0700 Subject: [PATCH 009/165] docs(qqbot): point install docs at the Tencent package (#122417) The externalization left the docs inventory seed and the channel page advertising the retired @openclaw/qqbot npm package; the catalog already resolves qqbot to @tencent-connect/openclaw-qqbot. Regenerates the plugin reference and inventory pages from the corrected seed. --- docs/channels/qqbot.md | 2 +- docs/plugins/plugin-inventory.md | 2 +- docs/plugins/reference/qqbot.md | 4 ++-- scripts/lib/official-external-channel-seed.json | 8 ++++---- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/channels/qqbot.md b/docs/channels/qqbot.md index 6e2bc76a212d..a495a5731826 100644 --- a/docs/channels/qqbot.md +++ b/docs/channels/qqbot.md @@ -19,7 +19,7 @@ Status: official downloadable plugin. ## Install ```bash -openclaw plugins install @openclaw/qqbot +openclaw plugins install @tencent-connect/openclaw-qqbot ``` ## Setup diff --git a/docs/plugins/plugin-inventory.md b/docs/plugins/plugin-inventory.md index 5636b08207da..7372af6298c7 100644 --- a/docs/plugins/plugin-inventory.md +++ b/docs/plugins/plugin-inventory.md @@ -298,7 +298,7 @@ Each entry lists the package, distribution route, and description. - **[qianfan](/plugins/reference/qianfan)** (`@openclaw/qianfan-provider`) - npm; ClawHub: `clawhub:@openclaw/qianfan-provider`. Adds Qianfan model provider support to OpenClaw. -- **[qqbot](/plugins/reference/qqbot)** (`@openclaw/qqbot`) - npm; ClawHub. OpenClaw QQ Bot channel plugin for group and direct-message workflows. +- **[qqbot](/plugins/reference/qqbot)** (`@tencent-connect/openclaw-qqbot`) - npm. OpenClaw QQ Bot channel plugin for group and direct-message workflows. - **[qwen](/plugins/reference/qwen)** (`@openclaw/qwen-provider`) - npm; ClawHub: `clawhub:@openclaw/qwen-provider`. Adds Qwen, Qwen Cloud, Model Studio, DashScope, Qwen Token Plan, Bailian Token Plan model provider support to OpenClaw. diff --git a/docs/plugins/reference/qqbot.md b/docs/plugins/reference/qqbot.md index 82468f74fb94..20ed68bd9600 100644 --- a/docs/plugins/reference/qqbot.md +++ b/docs/plugins/reference/qqbot.md @@ -11,8 +11,8 @@ OpenClaw QQ Bot channel plugin for group and direct-message workflows. ## Distribution -- Package: `@openclaw/qqbot` -- Install route: npm; ClawHub +- Package: `@tencent-connect/openclaw-qqbot` +- Install route: npm ## Surface diff --git a/scripts/lib/official-external-channel-seed.json b/scripts/lib/official-external-channel-seed.json index e9a50fcab04f..c75a4c9996f3 100644 --- a/scripts/lib/official-external-channel-seed.json +++ b/scripts/lib/official-external-channel-seed.json @@ -123,15 +123,15 @@ "docsSource": "official", "docsInventory": { "package": { - "name": "@openclaw/qqbot", - "description": "OpenClaw QQ Bot channel plugin for group and direct-message workflows.", + "name": "@tencent-connect/openclaw-qqbot", + "description": "OpenClaw QQ Bot channel plugin by the Tencent Connect team.", "openclaw": { "install": { - "npmSpec": "@openclaw/qqbot", + "npmSpec": "@tencent-connect/openclaw-qqbot", "defaultChoice": "npm" }, "release": { - "publishToClawHub": true, + "publishToClawHub": false, "publishToNpm": true } } From 722e20b67581092868f022f17b295ea1377a2400 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:22:42 -0700 Subject: [PATCH 010/165] test(agents): prune final Responses duplicates (#122424) * test(agents): prune final Responses duplicates * fix(tooling): honor inclusive compat removal dates --- config/max-lines-baseline.txt | 1 - scripts/plugin-boundary-report.ts | 16 +- .../openai-transport-stream.streaming.test.ts | 328 ------------------ test/scripts/plugin-boundary-report.test.ts | 13 + 4 files changed, 26 insertions(+), 332 deletions(-) diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt index 6e128a973367..9a81775995b3 100644 --- a/config/max-lines-baseline.txt +++ b/config/max-lines-baseline.txt @@ -397,7 +397,6 @@ src/agents/model-selection.test.ts src/agents/models.profiles.live.test.ts src/agents/openai-transport-stream.base.test.ts src/agents/openai-transport-stream.replay-and-tools.test.ts -src/agents/openai-transport-stream.streaming.test.ts src/agents/openclaw-tools.media-factory-plan.test.ts src/agents/openclaw-tools.session-status.test.ts src/agents/openclaw-tools.sessions.test.ts diff --git a/scripts/plugin-boundary-report.ts b/scripts/plugin-boundary-report.ts index 5c3e8ae5e045..55f69d7ed46a 100644 --- a/scripts/plugin-boundary-report.ts +++ b/scripts/plugin-boundary-report.ts @@ -403,6 +403,18 @@ function collectReferenceFiles(files: readonly WorkspaceTextFile[], tokens: read }; } +export function isPluginCompatEligibleForRemoval( + removeAfter: string | undefined, + today = new Date(), +): boolean { + if (!removeAfter) { + return false; + } + const firstRemovalInstant = new Date(`${removeAfter}T00:00:00Z`); + firstRemovalInstant.setUTCDate(firstRemovalInstant.getUTCDate() + 1); + return firstRemovalInstant <= today; +} + function collectCompatDebt( files: readonly WorkspaceTextFile[], today = new Date(), @@ -416,9 +428,7 @@ function collectCompatDebt( options.includeReferenceFiles === false ? { codeReferenceFiles: [], docReferenceFiles: [] } : collectReferenceFiles(files, tokens); - const eligibleForRemoval = record.removeAfter - ? new Date(`${record.removeAfter}T00:00:00Z`) <= today - : false; + const eligibleForRemoval = isPluginCompatEligibleForRemoval(record.removeAfter, today); return { code: record.code, owner: record.owner, diff --git a/src/agents/openai-transport-stream.streaming.test.ts b/src/agents/openai-transport-stream.streaming.test.ts index 231412da0bce..1859ca3985e9 100644 --- a/src/agents/openai-transport-stream.streaming.test.ts +++ b/src/agents/openai-transport-stream.streaming.test.ts @@ -777,333 +777,6 @@ describe("openai transport stream", () => { expect(events.filter((event) => event.type === "toolcall_end")).toHaveLength(2); }); - it("rejects a completed Responses tool call whose function name changed", async () => { - const model = createAzureResponsesModel(); - const output = createResponsesAssistantOutput(model); - - await expect( - testing.processResponsesStream( - streamChunks([ - { - type: "response.output_item.added", - output_index: 0, - item: { - type: "function_call", - id: "fc_name_conflict", - call_id: "call_name_conflict", - name: "read", - arguments: "", - }, - }, - { - type: "response.output_item.done", - output_index: 0, - item: { - type: "function_call", - id: "fc_name_conflict", - call_id: "call_name_conflict", - name: "write", - arguments: "{}", - }, - }, - ]), - output, - { push: vi.fn() }, - model, - ), - ).rejects.toThrow("Responses stream changed tool-call function name from read to write"); - }); - - it("routes an omitted-index suffix by item id across parallel Responses calls", async () => { - const model = createAzureResponsesModel(); - const output = createResponsesAssistantOutput(model); - const events: Array<{ type?: string; contentIndex?: number }> = []; - - await testing.processResponsesStream( - streamChunks([ - { - type: "response.output_item.added", - output_index: 0, - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: "", - }, - }, - { - type: "response.output_item.added", - output_index: 1, - item: { - type: "function_call", - id: "fc_second", - call_id: "call_second", - name: "computer", - arguments: "", - }, - }, - { - type: "response.function_call_arguments.delta", - output_index: 0, - item_id: "fc_first", - delta: '{"slot":', - }, - { - type: "response.function_call_arguments.delta", - item_id: "fc_first", - delta: "0}", - }, - { - type: "response.function_call_arguments.delta", - output_index: 1, - delta: '{"slot":1}', - }, - { - type: "response.output_item.done", - output_index: 0, - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: '{"slot":0}', - }, - }, - { - type: "response.output_item.done", - output_index: 1, - item: { - type: "function_call", - id: "fc_second", - call_id: "call_second", - name: "computer", - arguments: '{"slot":1}', - }, - }, - { - type: "response.completed", - response: { id: "resp_omitted_suffix", status: "completed" }, - }, - ]), - output, - { push: (event) => events.push(event as (typeof events)[number]) }, - model, - ); - - expect(output.content).toMatchObject([ - { type: "toolCall", id: "call_first|fc_first", arguments: { slot: 0 } }, - { type: "toolCall", id: "call_second|fc_second", arguments: { slot: 1 } }, - ]); - expect( - events.filter((event) => event.type === "toolcall_delta").map((event) => event.contentIndex), - ).toEqual([0, 0, 1]); - }); - - it("matches omitted-index parallel completions without duplicating indexed calls", async () => { - const model = createAzureResponsesModel(); - const output = createResponsesAssistantOutput(model); - const events: Array<{ type?: string; contentIndex?: number }> = []; - - await testing.processResponsesStream( - streamChunks([ - { - type: "response.output_item.added", - output_index: 0, - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: "", - }, - }, - { - type: "response.output_item.added", - output_index: 1, - item: { - type: "function_call", - id: "fc_second", - call_id: "call_second", - name: "computer", - arguments: "", - }, - }, - { - type: "response.function_call_arguments.delta", - output_index: 0, - item_id: "fc_first", - delta: '{"incomplete":', - }, - { - type: "response.output_item.done", - item: { - type: "function_call", - id: "fc_second", - call_id: "call_second", - name: "computer", - arguments: '{"slot":1}', - }, - }, - { - type: "response.output_item.done", - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: '{"slot":0}', - }, - }, - { - type: "response.completed", - response: { id: "resp_omitted_completions", status: "completed" }, - }, - ]), - output, - { push: (event) => events.push(event as (typeof events)[number]) }, - model, - ); - - expect(output.content).toMatchObject([ - { type: "toolCall", id: "call_first|fc_first", arguments: { slot: 0 } }, - { type: "toolCall", id: "call_second|fc_second", arguments: { slot: 1 } }, - ]); - expect(events.filter((event) => event.type === "toolcall_start")).toHaveLength(2); - expect(events.filter((event) => event.type === "toolcall_end")).toHaveLength(2); - }); - - it("rejects omitted-index events whose identity mismatches the sole indexed call", async () => { - const model = createAzureResponsesModel(); - const output = createResponsesAssistantOutput(model); - const events: Array<{ type?: string; contentIndex?: number }> = []; - - await testing.processResponsesStream( - streamChunks([ - { - type: "response.output_item.added", - output_index: 0, - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: "", - }, - }, - { - type: "response.function_call_arguments.delta", - item_id: "fc_other", - delta: '{"wrong":true}', - }, - { - type: "response.output_item.done", - item: { - type: "function_call", - id: "fc_other", - call_id: "call_other", - name: "computer", - arguments: '{"wrong":true}', - }, - }, - { - type: "response.output_item.done", - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: '{"slot":0}', - }, - }, - { - type: "response.completed", - response: { id: "resp_identity_mismatch", status: "completed" }, - }, - ]), - output, - { push: (event) => events.push(event as (typeof events)[number]) }, - model, - ); - - expect(output.content).toMatchObject([ - { type: "toolCall", id: "call_first|fc_first", arguments: { slot: 0 } }, - ]); - expect(events.filter((event) => event.type === "toolcall_start")).toHaveLength(1); - expect(events.filter((event) => event.type === "toolcall_delta")).toHaveLength(0); - expect(events.filter((event) => event.type === "toolcall_end")).toHaveLength(1); - }); - - it("keeps sequential omitted-index Responses calls unambiguous", async () => { - const model = createAzureResponsesModel(); - const output = createResponsesAssistantOutput(model); - const events: Array<{ type?: string; contentIndex?: number }> = []; - - await testing.processResponsesStream( - streamChunks([ - { - type: "response.output_item.added", - output_index: 7, - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: "", - }, - }, - { type: "response.function_call_arguments.delta", delta: '{"slot":0}' }, - { - type: "response.output_item.done", - item: { - type: "function_call", - id: "fc_first", - call_id: "call_first", - name: "computer", - arguments: '{"slot":0}', - }, - }, - { - type: "response.output_item.added", - output_index: 8, - item: { - type: "function_call", - id: "fc_second", - call_id: "call_second", - name: "computer", - arguments: "", - }, - }, - { type: "response.function_call_arguments.delta", delta: '{"slot":1}' }, - { - type: "response.output_item.done", - item: { - type: "function_call", - id: "fc_second", - call_id: "call_second", - name: "computer", - arguments: '{"slot":1}', - }, - }, - { - type: "response.completed", - response: { id: "resp_sequential_unindexed", status: "completed" }, - }, - ]), - output, - { push: (event) => events.push(event as (typeof events)[number]) }, - model, - ); - - expect(output.content).toMatchObject([ - { type: "toolCall", id: "call_first|fc_first", arguments: { slot: 0 } }, - { type: "toolCall", id: "call_second|fc_second", arguments: { slot: 1 } }, - ]); - expect( - events.filter((event) => event.type === "toolcall_delta").map((event) => event.contentIndex), - ).toEqual([0, 1]); - }); - it("handles Azure Responses text content and text delta events", async () => { const model = createAzureResponsesModel(); const output = createResponsesAssistantOutput(model); @@ -1166,4 +839,3 @@ describe("openai transport stream", () => { expect(output.responseId).toBe("resp_azure_text"); }); }); -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/test/scripts/plugin-boundary-report.test.ts b/test/scripts/plugin-boundary-report.test.ts index 185d2a4ef1ed..8422a4544fc0 100644 --- a/test/scripts/plugin-boundary-report.test.ts +++ b/test/scripts/plugin-boundary-report.test.ts @@ -2,6 +2,7 @@ import { beforeAll, describe, expect, it } from "vitest"; import { createPluginBoundaryReport, + isPluginCompatEligibleForRemoval, type PluginBoundaryReportResult, } from "../../scripts/plugin-boundary-report.js"; @@ -77,6 +78,18 @@ describe("plugin-boundary-report", () => { ); }); + it("treats removeAfter as the final compatibility day", () => { + expect( + isPluginCompatEligibleForRemoval("2026-08-12", new Date("2026-08-12T23:59:59.999Z")), + ).toBe(false); + expect( + isPluginCompatEligibleForRemoval("2026-08-12", new Date("2026-08-13T00:00:00.000Z")), + ).toBe(true); + expect(isPluginCompatEligibleForRemoval(undefined, new Date("2026-08-13T00:00:00.000Z"))).toBe( + false, + ); + }); + it("renders removal-pending blockers and reader references without changing fail gates", () => { const result = createPluginBoundaryReport(["--summary"]); From fc31a157cccb60244a320449d26f9dda728d3410 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:44:51 -0700 Subject: [PATCH 011/165] refactor(gateway): remove orphan testing aliases (#122433) --- src/gateway/call.ts | 1 - src/gateway/openresponses-http.ts | 1 - src/gateway/server-methods/agents.ts | 1 - 3 files changed, 3 deletions(-) diff --git a/src/gateway/call.ts b/src/gateway/call.ts index 4d22c7e395cb..dd18b956761d 100644 --- a/src/gateway/call.ts +++ b/src/gateway/call.ts @@ -1292,5 +1292,4 @@ export async function callGateway>( export function randomIdempotencyKey() { return randomUUID(); } -export { testing as __testing }; /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/src/gateway/openresponses-http.ts b/src/gateway/openresponses-http.ts index f6039accefbe..4c03f20288f1 100644 --- a/src/gateway/openresponses-http.ts +++ b/src/gateway/openresponses-http.ts @@ -1392,5 +1392,4 @@ export async function handleOpenResponsesHttpRequest( return true; } -export { testing as __testing }; /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/src/gateway/server-methods/agents.ts b/src/gateway/server-methods/agents.ts index 9a91f3d1f602..0c0e9f00d66f 100644 --- a/src/gateway/server-methods/agents.ts +++ b/src/gateway/server-methods/agents.ts @@ -1593,5 +1593,4 @@ export const agentsHandlers: GatewayRequestHandlers = { ); }, }; -export { testing as __testing }; /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ From cb52ded58d8f0ef51f379ea3347ad5afee8cf53d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:45:17 -0700 Subject: [PATCH 012/165] refactor(telegram): split native commands by executor (#122419) * refactor(telegram): split native commands by executor * refactor(telegram): deduplicate DM-thread target session * chore(lint): ratchet max-lines baseline after telegram commands split * test(telegram): fix native command split checks --- config/max-lines-baseline.txt | 2 - .../src/bot-handlers.callback-router.ts | 2 +- .../src/bot-handlers.message-context.ts | 19 +- .../src/bot-native-command-builtins.test.ts | 457 +++ .../src/bot-native-command-builtins.ts | 375 +++ ... bot-native-command-dispatch.auth.test.ts} | 0 ...t-native-command-dispatch.delivery.test.ts | 421 +++ ...ot-native-command-dispatch.routing.test.ts | 432 +++ ...ot-native-command-dispatch.test-support.ts | 107 + .../src/bot-native-command-dispatch.ts | 699 +++++ ...t-native-command-executors.test-support.ts | 580 ++++ ...st.ts => bot-native-command-login.test.ts} | 411 ++- .../telegram/src/bot-native-command-login.ts | 271 ++ .../src/bot-native-command-plugins.test.ts | 692 +++++ .../src/bot-native-command-plugins.ts | 316 +++ .../bot-native-commands.delivery.runtime.ts | 3 +- .../src/bot-native-commands.runtime.ts | 5 +- .../bot-native-commands.session-meta.test.ts | 2491 ----------------- .../telegram/src/bot-native-commands.test.ts | 545 +--- .../telegram/src/bot-native-commands.ts | 1953 +------------ extensions/telegram/src/conversation-route.ts | 30 +- .../src/native-command-callback-data.test.ts | 11 + 22 files changed, 4885 insertions(+), 4937 deletions(-) create mode 100644 extensions/telegram/src/bot-native-command-builtins.test.ts create mode 100644 extensions/telegram/src/bot-native-command-builtins.ts rename extensions/telegram/src/{bot-native-commands.group-auth.test.ts => bot-native-command-dispatch.auth.test.ts} (100%) create mode 100644 extensions/telegram/src/bot-native-command-dispatch.delivery.test.ts create mode 100644 extensions/telegram/src/bot-native-command-dispatch.routing.test.ts create mode 100644 extensions/telegram/src/bot-native-command-dispatch.test-support.ts create mode 100644 extensions/telegram/src/bot-native-command-dispatch.ts create mode 100644 extensions/telegram/src/bot-native-command-executors.test-support.ts rename extensions/telegram/src/{bot-native-commands.login.test.ts => bot-native-command-login.test.ts} (57%) create mode 100644 extensions/telegram/src/bot-native-command-login.ts create mode 100644 extensions/telegram/src/bot-native-command-plugins.test.ts create mode 100644 extensions/telegram/src/bot-native-command-plugins.ts delete mode 100644 extensions/telegram/src/bot-native-commands.session-meta.test.ts create mode 100644 extensions/telegram/src/native-command-callback-data.test.ts diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt index 9a81775995b3..27753e029aa0 100644 --- a/config/max-lines-baseline.txt +++ b/config/max-lines-baseline.txt @@ -247,8 +247,6 @@ extensions/slack/src/send.ts extensions/telegram/src/action-runtime.test.ts extensions/telegram/src/action-runtime.ts extensions/telegram/src/bot-message-context.session.ts -extensions/telegram/src/bot-native-commands.session-meta.test.ts -extensions/telegram/src/bot-native-commands.ts extensions/telegram/src/bot.create-telegram-bot.test.ts extensions/telegram/src/bot.test.ts extensions/telegram/src/bot/delivery.replies.ts diff --git a/extensions/telegram/src/bot-handlers.callback-router.ts b/extensions/telegram/src/bot-handlers.callback-router.ts index cc40fc2303cf..f26c2614bb55 100644 --- a/extensions/telegram/src/bot-handlers.callback-router.ts +++ b/extensions/telegram/src/bot-handlers.callback-router.ts @@ -38,7 +38,6 @@ import type { RegisterTelegramHandlerParams, TelegramCallbackRouter, } from "./bot-handlers.types.js"; -import { parseTelegramNativeCommandCallbackData } from "./bot-native-commands.js"; import { isTelegramSpooledReplayUpdate, recordTelegramMessageProcessingResult, @@ -63,6 +62,7 @@ import { } from "./model-buttons.js"; import { hasTelegramOpaqueCallbackPrefix, + parseTelegramNativeCommandCallbackData, parseTelegramOpaqueCallbackData, } from "./native-command-callback-data.js"; import { isTelegramMessageNotModifiedError } from "./network-errors.js"; diff --git a/extensions/telegram/src/bot-handlers.message-context.ts b/extensions/telegram/src/bot-handlers.message-context.ts index 88873980d04b..da0b7b5267d9 100644 --- a/extensions/telegram/src/bot-handlers.message-context.ts +++ b/extensions/telegram/src/bot-handlers.message-context.ts @@ -4,7 +4,6 @@ import { formatMediaPlaceholderText } from "openclaw/plugin-sdk/channel-inbound" import { resolveStoredModelOverride } from "openclaw/plugin-sdk/command-auth-native"; import type { OpenClawConfig, TelegramAccountConfig } from "openclaw/plugin-sdk/config-contracts"; import { DEFAULT_GROUP_HISTORY_LIMIT } from "openclaw/plugin-sdk/reply-history"; -import { resolveThreadSessionKeys } from "openclaw/plugin-sdk/routing"; import { getSessionEntry, readAmbientTranscriptWatermark, @@ -25,13 +24,12 @@ import { getTelegramTextParts, resolveTelegramPrimaryMedia, resolveTelegramForumThreadId, - shouldUseTelegramDmThreadSession, type TelegramThreadSpec, } from "./bot/helpers.js"; import type { TelegramContext } from "./bot/types.js"; import { - resolveTelegramConversationBaseSessionKey, resolveTelegramConversationRoute, + resolveTelegramTargetSession, } from "./conversation-route.js"; import { resolveTelegramDmHistoryLimit } from "./dm-history.js"; import { @@ -212,24 +210,15 @@ export function createTelegramMessageSessionRuntime({ senderId: params.senderId, topicAgentId: topicConfig?.agentId, }); - const baseSessionKey = resolveTelegramConversationBaseSessionKey({ + const sessionKey = resolveTelegramTargetSession({ cfg: params.runtimeCfg, route, chatId: params.chatId, isGroup: params.isGroup, senderId: params.senderId, + dmThreadId, + botHasTopicsEnabled: params.botHasTopicsEnabled, }); - const threadKeys = - shouldUseTelegramDmThreadSession({ - dmThreadId, - botHasTopicsEnabled: params.botHasTopicsEnabled, - }) && dmThreadId != null - ? resolveThreadSessionKeys({ - baseSessionKey, - threadId: `${params.chatId}:${dmThreadId}`, - }) - : null; - const sessionKey = threadKeys?.sessionKey ?? baseSessionKey; const storePath = telegramDeps.resolveStorePath(params.runtimeCfg.session?.store, { agentId: route.agentId, }); diff --git a/extensions/telegram/src/bot-native-command-builtins.test.ts b/extensions/telegram/src/bot-native-command-builtins.test.ts new file mode 100644 index 000000000000..ff59db837da4 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-builtins.test.ts @@ -0,0 +1,457 @@ +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +import { beforeEach, describe, expect, it } from "vitest"; +import { + executorTestMocks, + expectRecordFields, + expectSendMessageCall, + registerAndResolveCommandHandler, + resetSessionMetaMocks, +} from "./bot-native-command-executors.test-support.js"; +import { createTelegramPrivateCommandContext } from "./bot-native-commands.fixture-test-support.js"; + +const { agentRuntimeMocks, commandAuthMocks, replyMocks, sessionMocks } = executorTestMocks; + +describe("Telegram native command built-ins", () => { + beforeEach(resetSessionMetaMocks); + + it("uses the target session model when building native argument menus", async () => { + const cfg = { + agents: { + defaults: { + thinkingDefault: "low", + models: { + "anthropic/claude-opus-4-7": { + params: { thinking: "xhigh" }, + }, + }, + }, + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + providerOverride: "anthropic", + modelOverride: "claude-opus-4-7", + modelOverrideSource: "user", + thinkingLevel: "high", + updatedAt: 0, + }, + }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "think" && params.provider === "anthropic", + )?.[0]; + expectRecordFields( + menuCall, + { provider: "anthropic", model: "claude-opus-4-7" }, + "thinking menu call", + ); + expect(sessionMocks.getSessionEntry).toHaveBeenCalledWith({ + storePath: "/tmp/openclaw-sessions.json", + sessionKey: "agent:main:main", + }); + expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: "Current thinking level: high.\nChoose level for /think.", + requireReplyMarkup: true, + label: "thinking menu", + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it.each([ + { sessionRuntime: undefined, expectedRuntime: "codex" }, + { sessionRuntime: "openclaw", expectedRuntime: "openclaw" }, + ])( + "uses the effective $expectedRuntime runtime for native /think menus", + async ({ sessionRuntime, expectedRuntime }) => { + const cfg = { + agents: { + defaults: { + models: { + "openai/gpt-5.6-luna": { agentRuntime: { id: "codex" } }, + }, + }, + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + providerOverride: "openai", + modelOverride: "gpt-5.6-luna", + modelOverrideSource: "user", + ...(sessionRuntime ? { agentRuntimeOverride: sessionRuntime } : {}), + updatedAt: 0, + }, + }); + + const { handler } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "think" && params.model === "gpt-5.6-luna", + )?.[0]; + expectRecordFields( + menuCall, + { + provider: "openai", + model: "gpt-5.6-luna", + agentRuntime: expectedRuntime, + }, + "runtime-aware thinking menu call", + ); + }, + ); + + it("resolves /think menu choices against the runtime catalog for live-discovered models", async () => { + const cfg = { + agents: { defaults: { models: { "ollama/*": {} } } }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + providerOverride: "ollama", + modelOverride: "glm-5.2:cloud", + modelOverrideSource: "user", + updatedAt: 0, + }, + }); + const runtimeCatalog = [ + { provider: "ollama", id: "glm-5.2:cloud", name: "glm-5.2:cloud", reasoning: true }, + ]; + agentRuntimeMocks.loadModelCatalog.mockClear().mockResolvedValue(runtimeCatalog); + + const { handler } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "think" && params.provider === "ollama", + )?.[0]; + const menuRecord = expectRecordFields( + menuCall, + { provider: "ollama", model: "glm-5.2:cloud" }, + "ollama thinking menu call", + ); + expect(agentRuntimeMocks.loadModelCatalog).toHaveBeenCalled(); + expect(menuRecord.catalog).toEqual(runtimeCatalog); + }); + + it("loads the runtime catalog for /think when no session model override is set", async () => { + const cfg = { + agents: { defaults: { model: "ollama/glm-5.2:cloud", models: { "ollama/*": {} } } }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({}); + const runtimeCatalog = [ + { provider: "ollama", id: "glm-5.2:cloud", name: "glm-5.2:cloud", reasoning: true }, + ]; + agentRuntimeMocks.loadModelCatalog.mockClear().mockResolvedValue(runtimeCatalog); + + const { handler } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + expect(agentRuntimeMocks.loadModelCatalog).toHaveBeenCalled(); + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "think", + )?.[0]; + const menuRecord = expectRecordFields(menuCall, {}, "default-model thinking menu call"); + expect(menuRecord.provider).toBeUndefined(); + expect(menuRecord.catalog).toEqual(runtimeCatalog); + }); + + it("inherits the parent session model when building DM thread native argument menus", async () => { + const cfg: OpenClawConfig = {}; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + providerOverride: "anthropic", + modelOverride: "claude-opus-4-7", + modelOverrideSource: "user", + updatedAt: 0, + }, + }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext({ threadId: 77 })); + + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "think" && params.provider === "anthropic", + )?.[0]; + expectRecordFields( + menuCall, + { provider: "anthropic", model: "claude-opus-4-7" }, + "thread thinking menu call", + ); + expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: "Choose level for /think.", + requireReplyMarkup: true, + label: "thread thinking menu", + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it("uses the configured default model instead of temporary auto fallback overrides", async () => { + const cfg = { + agents: { + defaults: { + model: { primary: "openai/gpt-5.5" }, + thinkingDefault: "medium", + }, + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + providerOverride: "anthropic", + modelOverride: "claude-opus-4-7", + modelOverrideSource: "auto", + modelProvider: "anthropic", + model: "claude-opus-4-7", + updatedAt: 0, + }, + }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "think" && params.provider === "openai", + )?.[0]; + expectRecordFields( + menuCall, + { provider: "openai", model: "gpt-5.5" }, + "default model thinking menu call", + ); + expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: "Current thinking level: medium.\nChoose level for /think.", + requireReplyMarkup: true, + label: "default model thinking menu", + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it("uses configured model defaults instead of runtime auth metadata for the fast menu", async () => { + const cfg = { + agents: { + defaults: { + model: { primary: "openai/gpt-5.5" }, + models: { + "openai/gpt-5.5": { + params: { fastMode: "auto", fastAutoOnSeconds: 30 }, + }, + }, + }, + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + modelProvider: "openai-codex", + model: "gpt-5.5", + updatedAt: 0, + }, + }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "fast", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( + ([params]) => params.command.key === "fast", + )?.[0]; + expectRecordFields(menuCall, { cfg }, "fast menu call"); + expect( + commandAuthMocks.resolveCommandArgMenu.mock.calls.some( + ([params]) => + params.command.key === "fast" && + params.provider === "openai" && + params.model === "gpt-5.5", + ), + ).toBe(true); + const options = expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: + "Current fast mode: auto (30 sec) (default: model).\nOptions: on, off, auto (30 sec), default, status.", + requireReplyMarkup: true, + label: "fast menu", + }); + const replyMarkup = options.reply_markup as + | { inline_keyboard?: Array> } + | undefined; + const labels = (replyMarkup?.inline_keyboard ?? []).flatMap((row) => + row.map((button) => button.text), + ); + expect(labels).toContain("auto (30 sec)"); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it("uses the read-only catalog for Claude CLI thinking menus", async () => { + const cfg = { + agents: { + defaults: { + model: { primary: "anthropic/claude-opus-4-8" }, + }, + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({}); + agentRuntimeMocks.loadModelCatalog.mockImplementation(async (params) => { + if (!params?.readOnly) { + throw new Error("native /think must not start full model discovery"); + } + return [ + { + provider: "anthropic", + id: "claude-opus-4-8", + name: "Claude Opus 4.8", + reasoning: true, + }, + ]; + }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + expect(agentRuntimeMocks.loadModelCatalog).toHaveBeenCalledWith( + expect.objectContaining({ + config: cfg, + agentDir: expect.any(String), + readOnly: true, + }), + ); + expect(agentRuntimeMocks.loadModelCatalog.mock.calls[0]?.[0]).not.toHaveProperty( + "workspaceDir", + ); + expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: "Current thinking level: off.\nChoose level for /think.", + requireReplyMarkup: true, + label: "Claude CLI thinking menu", + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it("uses target model thinking defaults before global thinking defaults", async () => { + const cfg = { + agents: { + defaults: { + thinkingDefault: "low", + models: { + "anthropic/claude-opus-4-7": { + params: { thinking: "xhigh" }, + }, + }, + }, + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({ + "agent:main:main": { + providerOverride: "anthropic", + modelOverride: "claude-opus-4-7", + modelOverrideSource: "user", + updatedAt: 0, + }, + }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: "Current thinking level: xhigh.\nChoose level for /think.", + requireReplyMarkup: true, + label: "target model thinking menu", + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it("uses per-agent thinking defaults before target model and global thinking defaults", async () => { + const cfg = { + agents: { + defaults: { + thinkingDefault: "low", + models: { + "anthropic/claude-opus-4-7": { + params: { thinking: "xhigh" }, + }, + }, + }, + list: [ + { + id: "alpha", + model: { primary: "anthropic/claude-opus-4-7" }, + thinkingDefault: "minimal", + }, + ], + }, + } as OpenClawConfig; + sessionMocks.sessionStoreEntries.mockReturnValue({}); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "think", + cfg, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext()); + + expectSendMessageCall({ + sendMessage, + chatId: 100, + textIncludes: "Current thinking level: minimal.\nChoose level for /think.", + requireReplyMarkup: true, + label: "agent thinking menu", + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + }); + + it("does not load the session store when a native argument menu is skipped", async () => { + const { handler } = registerAndResolveCommandHandler({ + commandName: "think", + cfg: {}, + allowFrom: ["*"], + }); + await handler(createTelegramPrivateCommandContext({ match: "high" })); + + expect(sessionMocks.sessionStoreEntries).not.toHaveBeenCalled(); + expect(agentRuntimeMocks.loadModelCatalog).not.toHaveBeenCalled(); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1); + }); +}); diff --git a/extensions/telegram/src/bot-native-command-builtins.ts b/extensions/telegram/src/bot-native-command-builtins.ts new file mode 100644 index 000000000000..b59c9321b4b9 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-builtins.ts @@ -0,0 +1,375 @@ +// Telegram plugin module implements built-in native command behavior. +import { + loadPreparedModelCatalog, + resolveAgentConfig, + resolveAgentDir, + resolveDefaultModelForAgent, + resolveThinkingDefaultWithRuntimeCatalog, +} from "openclaw/plugin-sdk/agent-runtime"; +import { + buildCommandTextFromArgs, + findCommandByNativeName, + formatCommandArgMenuTitle, + formatFastModeCurrentStatus, + parseCommandArgs, + resolveCommandArgMenu, + resolveEffectiveAgentRuntime, + resolveFastModeState, + resolveStoredModelOverride, + type CommandArgs, +} from "openclaw/plugin-sdk/command-auth-native"; +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime"; +import { + getSessionEntry, + resolveStorePath, + type SessionEntry, +} from "openclaw/plugin-sdk/session-store-runtime"; +import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime"; +import { withTelegramApiErrorLogging } from "./api-logging.js"; +import { + dispatchTelegramBuiltinTurn, + prepareTelegramCommandDispatch, + type TelegramCommandExecutorParams, +} from "./bot-native-command-dispatch.js"; +import { buildInlineKeyboard } from "./inline-keyboard.js"; +import { buildTelegramNativeCommandCallbackData } from "./native-command-callback-data.js"; + +const loadTelegramLoginCommandExecutor = createLazyRuntimeModule( + () => import("./bot-native-command-login.js"), +); + +type TelegramCommandMenuModelContext = { + provider?: string; + model?: string; + agentRuntime?: string; + thinkingLevel?: string; + fastMode?: SessionEntry["fastMode"]; +}; + +function buildTelegramCommandMenuModelContext(params: { + provider: string; + model: string; + thinkingLevel?: string; + fastMode?: SessionEntry["fastMode"]; +}): TelegramCommandMenuModelContext { + return { + provider: params.provider, + model: params.model, + ...(params.thinkingLevel ? { thinkingLevel: params.thinkingLevel } : {}), + ...(params.fastMode !== undefined ? { fastMode: params.fastMode } : {}), + }; +} + +function resolveTelegramCommandMenuModelContext(params: { + cfg: OpenClawConfig; + agentId: string; + sessionKey: string; +}): TelegramCommandMenuModelContext { + if (!params.sessionKey.trim()) { + return {}; + } + try { + const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); + const defaultModel = resolveDefaultModelForAgent({ cfg: params.cfg, agentId: params.agentId }); + const entry = getSessionEntry({ storePath, sessionKey: params.sessionKey }); + const thinkingLevel = normalizeOptionalString(entry?.thinkingLevel); + const fastMode = entry?.fastMode; + let context: TelegramCommandMenuModelContext; + if (entry?.modelOverrideSource === "auto" && normalizeOptionalString(entry.modelOverride)) { + context = buildTelegramCommandMenuModelContext({ + provider: defaultModel.provider, + model: defaultModel.model, + ...(thinkingLevel ? { thinkingLevel } : {}), + ...(fastMode !== undefined ? { fastMode } : {}), + }); + } else { + const override = resolveStoredModelOverride({ + sessionEntry: entry, + loadSessionEntry: (sessionKey) => getSessionEntry({ storePath, sessionKey }), + sessionKey: params.sessionKey, + defaultProvider: defaultModel.provider, + }); + if (override?.model) { + context = buildTelegramCommandMenuModelContext({ + provider: override.provider || defaultModel.provider, + model: override.model, + ...(thinkingLevel ? { thinkingLevel } : {}), + ...(fastMode !== undefined ? { fastMode } : {}), + }); + } else { + const provider = + normalizeOptionalString(entry?.providerOverride) ?? + normalizeOptionalString(entry?.modelProvider); + const model = + normalizeOptionalString(entry?.modelOverride) ?? normalizeOptionalString(entry?.model); + context = { + ...(provider ? { provider } : {}), + ...(model ? { model } : {}), + ...(thinkingLevel ? { thinkingLevel } : {}), + ...(fastMode !== undefined ? { fastMode } : {}), + }; + } + } + return { + ...context, + agentRuntime: resolveEffectiveAgentRuntime({ + cfg: params.cfg, + provider: context.provider ?? defaultModel.provider, + modelId: context.model ?? defaultModel.model, + agentId: params.agentId, + sessionKey: params.sessionKey, + sessionEntry: entry, + }), + }; + } catch { + return {}; + } +} + +function resolveTelegramFastCommandModelContext(params: { + cfg: OpenClawConfig; + agentId: string; + sessionKey: string; +}): { provider?: string; model?: string } { + const defaultModel = resolveDefaultModelForAgent({ cfg: params.cfg, agentId: params.agentId }); + const fallback = () => ({ provider: defaultModel.provider, model: defaultModel.model }); + if (!params.sessionKey.trim()) { + return fallback(); + } + try { + const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); + const entry = getSessionEntry({ storePath, sessionKey: params.sessionKey }); + if (entry?.modelOverrideSource === "auto" && normalizeOptionalString(entry.modelOverride)) { + return fallback(); + } + const override = resolveStoredModelOverride({ + sessionEntry: entry, + loadSessionEntry: (sessionKey) => getSessionEntry({ storePath, sessionKey }), + sessionKey: params.sessionKey, + defaultProvider: defaultModel.provider, + }); + return { + provider: override?.provider ?? defaultModel.provider, + model: override?.model ?? defaultModel.model, + }; + } catch { + return fallback(); + } +} + +function resolveTelegramFastCommandState(params: { + cfg: OpenClawConfig; + agentId: string; + sessionKey: string; +}) { + const defaultModel = resolveDefaultModelForAgent({ cfg: params.cfg, agentId: params.agentId }); + const fallback = () => + resolveFastModeState({ + cfg: params.cfg, + provider: defaultModel.provider, + model: defaultModel.model, + agentId: params.agentId, + }); + if (!params.sessionKey.trim()) { + return fallback(); + } + try { + const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); + const entry = getSessionEntry({ storePath, sessionKey: params.sessionKey }); + const modelContext = resolveTelegramFastCommandModelContext(params); + return resolveFastModeState({ + cfg: params.cfg, + provider: modelContext.provider ?? defaultModel.provider, + model: modelContext.model ?? defaultModel.model, + agentId: params.agentId, + sessionEntry: + entry?.fastMode !== undefined + ? { + fastMode: entry.fastMode, + } + : undefined, + }); + } catch { + return fallback(); + } +} + +async function resolveTelegramThinkMenuCurrentLevel(params: { + cfg: OpenClawConfig; + agentId: string; + provider?: string; + model?: string; + agentRuntime?: string; + thinkingLevel?: string; + catalog: Awaited>; +}): Promise { + const explicit = normalizeOptionalString(params.thinkingLevel); + if (explicit) { + return explicit; + } + const agentThinkingDefault = normalizeOptionalString( + resolveAgentConfig(params.cfg, params.agentId)?.thinkingDefault, + ); + if (agentThinkingDefault) { + return agentThinkingDefault; + } + const defaultModel = resolveDefaultModelForAgent({ cfg: params.cfg, agentId: params.agentId }); + return await resolveThinkingDefaultWithRuntimeCatalog({ + cfg: params.cfg, + provider: params.provider ?? defaultModel.provider, + model: params.model ?? defaultModel.model, + agentRuntime: params.agentRuntime, + loadRuntimeCatalog: async () => params.catalog, + }); +} + +function formatTelegramCommandArgMenuTitle(params: { + command: NonNullable>; + menu: NonNullable>; + currentThinkingLevel?: string; + currentFastModeStatus?: string; +}): string { + const title = formatCommandArgMenuTitle({ command: params.command, menu: params.menu }); + if (params.command.key === "think" && params.currentThinkingLevel) { + return `Current thinking level: ${params.currentThinkingLevel}.\n${title}`; + } + if (params.command.key === "fast" && params.currentFastModeStatus) { + const options = params.menu.choices + .map((choice) => choice.label.trim()) + .filter(Boolean) + .join(", "); + return options + ? `${params.currentFastModeStatus}\nOptions: ${options}.` + : params.currentFastModeStatus; + } + return title; +} + +export async function executeTelegramBuiltinCommand( + params: TelegramCommandExecutorParams & { commandName: string }, +): Promise { + const dispatch = await prepareTelegramCommandDispatch({ ...params, requireAuth: true }); + if (!dispatch) { + return false; + } + const commandDefinition = findCommandByNativeName(params.commandName, "telegram"); + const commandArgs = commandDefinition + ? parseCommandArgs(commandDefinition, params.rawText) + : params.rawText + ? ({ raw: params.rawText } satisfies CommandArgs) + : undefined; + const prompt = commandDefinition + ? buildCommandTextFromArgs(commandDefinition, commandArgs) + : params.rawText + ? `/${params.commandName} ${params.rawText}` + : `/${params.commandName}`; + if (commandDefinition?.key === "login") { + const { executeTelegramLoginCommand } = await loadTelegramLoginCommandExecutor(); + return await executeTelegramLoginCommand({ dispatch, commandArgs }); + } + + const menuNeedsModelContext = + commandDefinition?.argsMenu && + !(commandArgs?.raw && !commandArgs.values) && + commandDefinition.args?.some( + (arg) => typeof arg.choices === "function" && commandArgs?.values?.[arg.name] == null, + ); + const sessionKeyForMenu = + commandDefinition && menuNeedsModelContext ? dispatch.targetSessionKey : ""; + const fastCommandState = + commandDefinition?.key === "fast" && menuNeedsModelContext + ? resolveTelegramFastCommandState({ + cfg: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + sessionKey: sessionKeyForMenu, + }) + : undefined; + const fastMenuModelContext = + commandDefinition?.key === "fast" && menuNeedsModelContext + ? resolveTelegramFastCommandModelContext({ + cfg: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + sessionKey: sessionKeyForMenu, + }) + : undefined; + const menuModelContext = + commandDefinition && menuNeedsModelContext + ? (fastMenuModelContext ?? + resolveTelegramCommandMenuModelContext({ + cfg: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + sessionKey: sessionKeyForMenu, + })) + : {}; + // Native /think must not wait on provider discovery; persisted rows retain its metadata. + const menuModelCatalog = + commandDefinition?.key === "think" && menuNeedsModelContext + ? await loadPreparedModelCatalog({ + config: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + agentDir: resolveAgentDir(dispatch.runtimeCfg, dispatch.route.agentId), + readOnly: true, + }) + : undefined; + const menu = commandDefinition + ? resolveCommandArgMenu({ + command: commandDefinition, + args: commandArgs, + cfg: dispatch.runtimeCfg, + ...menuModelContext, + ...(menuModelCatalog?.length ? { catalog: menuModelCatalog } : {}), + }) + : null; + if (menu && commandDefinition) { + const title = formatTelegramCommandArgMenuTitle({ + command: commandDefinition, + menu, + currentThinkingLevel: + commandDefinition.key === "think" + ? await resolveTelegramThinkMenuCurrentLevel({ + cfg: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + ...menuModelContext, + catalog: menuModelCatalog ?? [], + }) + : undefined, + currentFastModeStatus: + commandDefinition.key === "fast" + ? formatFastModeCurrentStatus({ + ...(fastCommandState ?? + resolveTelegramFastCommandState({ + cfg: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + sessionKey: sessionKeyForMenu, + })), + }) + : undefined, + }); + const rows: Array> = []; + for (let index = 0; index < menu.choices.length; index += 2) { + rows.push( + menu.choices.slice(index, index + 2).map((choice) => ({ + text: choice.label, + callback_data: buildTelegramNativeCommandCallbackData( + buildCommandTextFromArgs(commandDefinition, { + values: { [menu.arg.name]: choice.value }, + }), + ), + })), + ); + } + const replyMarkup = buildInlineKeyboard(rows); + await withTelegramApiErrorLogging({ + operation: "sendMessage", + runtime: dispatch.runtime, + fn: () => + dispatch.bot.api.sendMessage(dispatch.chatId, title, { + ...(replyMarkup ? { reply_markup: replyMarkup } : {}), + ...dispatch.threadParams, + }), + }); + return false; + } + return await dispatchTelegramBuiltinTurn({ dispatch, prompt, commandArgs }); +} diff --git a/extensions/telegram/src/bot-native-commands.group-auth.test.ts b/extensions/telegram/src/bot-native-command-dispatch.auth.test.ts similarity index 100% rename from extensions/telegram/src/bot-native-commands.group-auth.test.ts rename to extensions/telegram/src/bot-native-command-dispatch.auth.test.ts diff --git a/extensions/telegram/src/bot-native-command-dispatch.delivery.test.ts b/extensions/telegram/src/bot-native-command-dispatch.delivery.test.ts new file mode 100644 index 000000000000..47eebf8d0b90 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-dispatch.delivery.test.ts @@ -0,0 +1,421 @@ +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { + createChannelPartialDeliveryError, + createDeferred, + dispatchReplyResult, + dispatchChannelInboundTurnMock, + executorTestMocks, + firstMockArg, + registerAndResolveStatusHandler, + requireRecord, + requireValue, + resetSessionMetaMocks, +} from "./bot-native-command-executors.test-support.js"; +import type { DispatchReplyWithBufferedBlockDispatcherParams } from "./bot-native-command-executors.test-support.js"; +import { createTelegramPrivateCommandContext } from "./bot-native-commands.fixture-test-support.js"; + +type DeliverRepliesParams = Parameters[0]; + +const { deliveryMocks, replyMocks, sessionMocks } = executorTestMocks; + +describe("Telegram native command dispatch delivery", () => { + beforeEach(resetSessionMetaMocks); + + it("awaits routed session metadata persistence before command dispatch", async () => { + const deferred = createDeferred(); + sessionMocks.recordSessionMetaFromInbound.mockReturnValue(deferred.promise); + + const cfg: OpenClawConfig = {}; + const { handler } = registerAndResolveStatusHandler({ cfg }); + const runPromise = handler(createTelegramPrivateCommandContext()); + + await vi.waitFor(() => { + expect(sessionMocks.recordSessionMetaFromInbound).toHaveBeenCalledTimes(1); + }); + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + + deferred.resolve(); + await runPromise; + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1); + + const dispatcherOptions = requireRecord( + requireRecord( + firstMockArg( + replyMocks.dispatchReplyWithBufferedBlockDispatcher, + "dispatchReplyWithBufferedBlockDispatcher", + ), + "dispatch reply params", + ).dispatcherOptions, + "dispatcher options", + ); + expect(dispatcherOptions.beforeDeliver).toBeTypeOf("function"); + }); + + it("does not inject approval buttons for native command replies once the monitor owns approvals", async () => { + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce( + async ({ dispatcherOptions }: DispatchReplyWithBufferedBlockDispatcherParams) => { + await dispatcherOptions.deliver( + { + text: "Mode: foreground\nRun: /approve 7f423fdc allow-once (or allow-always / deny).", + }, + { kind: "final" }, + ); + return dispatchReplyResult; + }, + ); + + const { handler } = registerAndResolveStatusHandler({ + cfg: { + channels: { + telegram: { + execApprovals: { + enabled: true, + approvers: ["12345"], + target: "dm", + }, + }, + }, + }, + }); + await handler(createTelegramPrivateCommandContext()); + + const deliveredCall = firstMockArg(deliveryMocks.deliverReplies, "deliverReplies") as + | DeliverRepliesParams + | undefined; + const deliveredPayload = deliveredCall?.replies?.[0]; + if (!deliveredPayload) { + throw new Error("expected approval reply payload to be delivered"); + } + expect(deliveredPayload?.["text"]).toContain("/approve 7f423fdc allow-once"); + expect(deliveredPayload?.["channelData"]).toBeUndefined(); + }); + + it("suppresses local structured exec approval replies for native commands", async () => { + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce( + async ({ dispatcherOptions }: DispatchReplyWithBufferedBlockDispatcherParams) => { + await dispatcherOptions.deliver( + { + text: "Approval required.\n\n```txt\n/approve 7f423fdc allow-once\n```", + channelData: { + execApproval: { + approvalId: "7f423fdc-1111-2222-3333-444444444444", + approvalSlug: "7f423fdc", + allowedDecisions: ["allow-once", "allow-always", "deny"], + }, + }, + }, + { kind: "tool" }, + ); + return dispatchReplyResult; + }, + ); + + const { handler } = registerAndResolveStatusHandler({ + cfg: { + channels: { + telegram: { + execApprovals: { + enabled: true, + approvers: ["12345"], + target: "dm", + }, + }, + }, + }, + }); + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); + }); + + it("does not emit the empty fallback when reply-payload hooks cancel a native reply", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + await plan.delivery.onDelivered?.( + { text: "cancelled" }, + { kind: "final" }, + { + visibleReplySent: false, + suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, + }, + ); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); + }); + + it("does not emit the empty fallback for a message-tool-only native reply", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + plan.dispatcherOptions?.onSkip?.({}, { kind: "final", reason: "empty" }); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + sourceReplyDeliveryMode: "message_tool_only", + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); + }); + + it("retains the native fallback when message-tool-only delivery also fails", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + plan.dispatcherOptions?.onSkip?.({}, { kind: "final", reason: "empty" }); + plan.delivery.onError?.(new Error("Telegram final delivery failed"), { + kind: "final", + }); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + sourceReplyDeliveryMode: "message_tool_only", + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); + expect(deliveryMocks.deliverReplies).toHaveBeenCalledWith( + expect.objectContaining({ + replies: [{ text: "No response generated. Please try again." }], + }), + ); + }); + + it("emits the fallback when a non-final suppression precedes a final failure", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + await plan.delivery.onDelivered?.( + { text: "cancelled tool reply" }, + { kind: "tool" }, + { + visibleReplySent: false, + suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, + }, + ); + plan.delivery.onError?.(new Error("Telegram final delivery failed"), { + kind: "final", + }); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); + expect(deliveryMocks.deliverReplies).toHaveBeenCalledWith( + expect.objectContaining({ + replies: [{ text: "No response generated. Please try again." }], + }), + ); + }); + + it("emits the fallback when a suppressed block reply precedes a final failure", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + await plan.delivery.onDelivered?.( + { text: "cancelled block reply" }, + { kind: "block" }, + { + visibleReplySent: false, + suppression: { reason: "empty_after_reply_payload_sending_hook" }, + }, + ); + plan.delivery.onError?.(new Error("Telegram final delivery failed"), { + kind: "final", + }); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); + }); + + it("emits the fallback when a final failure precedes a later suppressed final", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + plan.delivery.onError?.(new Error("Telegram final delivery failed"), { + kind: "final", + }); + await plan.delivery.onDelivered?.( + { text: "cancelled final reply" }, + { kind: "final" }, + { + visibleReplySent: false, + suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, + }, + ); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); + }); + + it("preserves a suppressed final after a non-final delivery failure", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + plan.delivery.onError?.(new Error("Telegram tool delivery failed"), { + kind: "tool", + }); + await plan.delivery.onDelivered?.( + { text: "cancelled final reply" }, + { kind: "final" }, + { + visibleReplySent: false, + suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, + }, + ); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); + }); + + it("does not emit the fallback after a partially delivered final", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + plan.delivery.onError?.( + createChannelPartialDeliveryError(new Error("Telegram final delivery failed"), { + visibleReplySent: true, + }), + { kind: "final" }, + ); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); + }); + + it("retains the empty fallback for a true non-silent metadata-only native reply", async () => { + dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { + plan.dispatcherOptions?.onSkip?.({}, { kind: "final", reason: "empty" }); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult: { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }, + }; + }); + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + await handler(createTelegramPrivateCommandContext()); + + expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); + expect(deliveryMocks.deliverReplies).toHaveBeenCalledWith( + expect.objectContaining({ + replies: [{ text: "No response generated. Please try again." }], + }), + ); + }); + + it("sends native command error replies silently when silentErrorReplies is enabled", async () => { + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce( + async ({ dispatcherOptions }: DispatchReplyWithBufferedBlockDispatcherParams) => { + await dispatcherOptions.deliver({ text: "oops", isError: true }, { kind: "final" }); + return dispatchReplyResult; + }, + ); + + const { handler } = registerAndResolveStatusHandler({ + cfg: { + channels: { + telegram: { + silentErrorReplies: true, + }, + }, + }, + telegramCfg: { silentErrorReplies: true }, + }); + await handler(createTelegramPrivateCommandContext()); + + const deliveredCall = firstMockArg(deliveryMocks.deliverReplies, "deliverReplies") as + | DeliverRepliesParams + | undefined; + const deliveryParams = requireValue(deliveredCall, "silent error delivery params"); + expect(deliveryParams.silent).toBe(true); + expect(deliveryParams.replies).toHaveLength(1); + expect(deliveryParams.replies[0]?.isError).toBe(true); + }); +}); diff --git a/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts b/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts new file mode 100644 index 000000000000..30146d6946bd --- /dev/null +++ b/extensions/telegram/src/bot-native-command-dispatch.routing.test.ts @@ -0,0 +1,432 @@ +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { + createConfiguredAcpTopicBinding, + createConfiguredBindingRoute, +} from "./bot-native-command-dispatch.test-support.js"; +import { + activePluginRegistry, + dispatchChannelInboundTurnMock, + executorTestMocks, + expectRecordFields, + expectSendMessageCall, + expectUnauthorizedNewCommandBlocked, + firstMockArg, + registerAndResolveCommandHandler, + registerAndResolveStatusHandler, + requireRecord, + resetSessionMetaMocks, + runWithTelegramUpdateProcessingFrame, +} from "./bot-native-command-executors.test-support.js"; +import { + createTelegramGroupCommandContext, + createTelegramPrivateCommandContext, + createTelegramTopicCommandContext, +} from "./bot-native-commands.fixture-test-support.js"; + +const { persistentBindingMocks, replyMocks, sessionBindingMocks, sessionMocks } = executorTestMocks; + +describe("Telegram native command dispatch routing", () => { + beforeEach(resetSessionMetaMocks); + + it("calls recordSessionMetaFromInbound after a native slash command", async () => { + const shadowHandler = vi.fn(async () => ({ text: "wrong plugin" })); + activePluginRegistry.commands.push({ + pluginId: "shadow-plugin", + source: "test", + command: { + name: "status", + description: "Shadow status", + channels: ["telegram"], + requireAuth: false, + handler: shadowHandler, + }, + }); + const cfg: OpenClawConfig = {}; + const { handler } = registerAndResolveStatusHandler({ cfg }); + await handler(createTelegramPrivateCommandContext()); + + expect(sessionMocks.recordSessionMetaFromInbound).toHaveBeenCalledTimes(1); + expect(shadowHandler).not.toHaveBeenCalled(); + const turnPlan = dispatchChannelInboundTurnMock.mock.calls[0]?.[0]; + expect(turnPlan?.replyOptions?.[Symbol.for("openclaw.pluginCommandDispatch") as never]).toEqual( + { kind: "non-plugin" }, + ); + const call = ( + sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< + [{ sessionKey?: string; ctx?: { OriginatingChannel?: string; Provider?: string } }] + > + )[0]?.[0]; + expect(call?.ctx?.OriginatingChannel).toBe("telegram"); + expect(call?.ctx?.Provider).toBe("telegram"); + expect(call?.sessionKey).toBe(turnPlan?.ctxPayload.CommandTargetSessionKey); + expect(turnPlan?.record?.sessionKey).toBe(turnPlan?.ctxPayload.CommandTargetSessionKey); + }); + + it("leaves native-command outcomes to the update middleware owner", async () => { + const { handler } = registerAndResolveStatusHandler({ cfg: {} }); + + const { result } = await runWithTelegramUpdateProcessingFrame(async () => { + await handler(createTelegramPrivateCommandContext()); + }); + + expect(result).toBeUndefined(); + }); + + it("preserves every argument on native queue command turns", async () => { + const { handler } = registerAndResolveCommandHandler({ + commandName: "queue", + cfg: {}, + allowFrom: ["*"], + }); + + await handler(createTelegramPrivateCommandContext({ match: "Can you diagnose this?" })); + + expect(dispatchChannelInboundTurnMock).toHaveBeenCalledWith( + expect.objectContaining({ + ctxPayload: expect.objectContaining({ + Body: "/queue Can you diagnose this?", + CommandBody: "/queue Can you diagnose this?", + CommandTurn: expect.objectContaining({ + kind: "native", + body: "/queue Can you diagnose this?", + }), + }), + }), + ); + }); + + it("keeps one live config snapshot through native command execution", async () => { + const startupCfg: OpenClawConfig = { session: { store: "/tmp/startup-sessions.json" } }; + const runtimeCfg: OpenClawConfig = { session: { store: "/tmp/runtime-sessions.json" } }; + const { handler } = registerAndResolveStatusHandler({ cfg: startupCfg, runtimeCfg }); + + await handler(createTelegramPrivateCommandContext()); + + const dispatchCall = requireRecord( + firstMockArg( + replyMocks.dispatchReplyWithBufferedBlockDispatcher, + "dispatchReplyWithBufferedBlockDispatcher", + ), + "dispatch call", + ); + expect(dispatchCall.cfg).toBe(runtimeCfg); + }); + + it.each([ + { blockStreamingEnabled: false, expectedDisableBlockStreaming: true }, + { blockStreamingEnabled: true, expectedDisableBlockStreaming: false }, + ])( + "uses nested streaming.block.enabled=$blockStreamingEnabled for native command dispatch", + async ({ blockStreamingEnabled, expectedDisableBlockStreaming }) => { + const cfg = { + channels: { + telegram: { + streaming: { block: { enabled: blockStreamingEnabled } }, + }, + }, + } satisfies OpenClawConfig; + const { handler } = registerAndResolveStatusHandler({ cfg }); + + await handler(createTelegramPrivateCommandContext()); + + const dispatchCall = requireRecord( + firstMockArg( + replyMocks.dispatchReplyWithBufferedBlockDispatcher, + "dispatchReplyWithBufferedBlockDispatcher", + ), + "dispatch call", + ); + expect(dispatchCall.replyOptions).toMatchObject({ + disableBlockStreaming: expectedDisableBlockStreaming, + }); + }, + ); + + it("routes Telegram native commands through configured ACP topic bindings", async () => { + const boundSessionKey = "agent:codex:acp:binding:telegram:default:feedface"; + persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => + createConfiguredBindingRoute( + { + ...route, + sessionKey: boundSessionKey, + agentId: "codex", + matchedBy: "binding.channel", + }, + createConfiguredAcpTopicBinding(boundSessionKey), + ), + ); + persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ ok: true }); + + const { handler } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: ["200"], + groupAllowFrom: ["200"], + }); + await handler(createTelegramTopicCommandContext()); + + expect(persistentBindingMocks.resolveConfiguredBindingRoute).toHaveBeenCalledTimes(1); + expect(persistentBindingMocks.ensureConfiguredBindingRouteReady).toHaveBeenCalledTimes(1); + const dispatchCall = ( + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< + [{ ctx?: { CommandTargetSessionKey?: string } }] + > + )[0]?.[0]; + expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe(boundSessionKey); + const sessionMetaCall = ( + sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< + [{ sessionKey?: string }] + > + )[0]?.[0]; + expect(sessionMetaCall?.sessionKey).toBe(boundSessionKey); + }); + + it("routes Telegram native commands through topic-specific agent sessions", async () => { + const { handler } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: ["200"], + groupAllowFrom: ["200"], + resolveTelegramGroupConfig: () => ({ + groupConfig: { requireMention: false }, + topicConfig: { agentId: "zu" }, + }), + }); + await handler(createTelegramTopicCommandContext()); + + const dispatchCall = ( + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< + [{ ctx?: { CommandTargetSessionKey?: string } }] + > + )[0]?.[0]; + expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe( + "agent:zu:telegram:group:-1001234567890:topic:42", + ); + const sessionMetaCall = ( + sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< + [{ sessionKey?: string; ctx?: { From?: string; ChatType?: string } }] + > + )[0]?.[0]; + expect(sessionMetaCall?.sessionKey).toBe("agent:zu:telegram:group:-1001234567890:topic:42"); + expect(sessionMetaCall?.ctx?.From).toBe("telegram:group:-1001234567890:topic:42"); + expect(sessionMetaCall?.ctx?.ChatType).toBe("group"); + }); + + it("does not mark paired Telegram DM allowlist entries as native group command owners", async () => { + const { handler, sendMessage } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: [], + groupAllowFrom: [], + storeAllowFrom: ["200"], + }); + await handler(createTelegramTopicCommandContext()); + + expectUnauthorizedNewCommandBlocked(sendMessage); + }); + + it("authorizes paired Telegram DMs without marking them as owners", async () => { + const { handler } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: [], + groupAllowFrom: [], + storeAllowFrom: ["200"], + }); + await handler(createTelegramPrivateCommandContext()); + + const dispatchCall = ( + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< + [ + { + ctx?: { + CommandAuthorized?: boolean; + }; + }, + ] + > + )[0]?.[0]; + expect(dispatchCall?.ctx?.CommandAuthorized).toBe(true); + expect(dispatchCall?.ctx).not.toHaveProperty("OwnerAllowFrom"); + }); + + it("routes Telegram native commands through bound topic sessions", async () => { + sessionBindingMocks.resolveByConversation.mockReturnValue({ + bindingId: "default:-1001234567890:topic:42", + targetSessionKey: "agent:codex-acp:session-1", + }); + + const { handler } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: ["200"], + groupAllowFrom: ["200"], + }); + await handler(createTelegramTopicCommandContext()); + + expect(sessionBindingMocks.resolveByConversation).toHaveBeenCalledWith({ + channel: "telegram", + accountId: "default", + conversationId: "-1001234567890:topic:42", + }); + const dispatchCall = ( + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< + [{ ctx?: { CommandTargetSessionKey?: string } }] + > + )[0]?.[0]; + expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe("agent:codex-acp:session-1"); + const sessionMetaCall = ( + sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< + [{ sessionKey?: string }] + > + )[0]?.[0]; + expect(sessionMetaCall?.sessionKey).toBe("agent:codex-acp:session-1"); + expect(sessionBindingMocks.touch).toHaveBeenCalledWith( + "default:-1001234567890:topic:42", + undefined, + ); + }); + + it("routes Telegram native commands through bound top-level group sessions", async () => { + sessionBindingMocks.resolveByConversation.mockReturnValue({ + bindingId: "default:-1001234567890", + targetSessionKey: "agent:codex-acp:session-group", + }); + + const { handler } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: ["200"], + groupAllowFrom: ["200"], + }); + await handler(createTelegramGroupCommandContext()); + + expect(sessionBindingMocks.resolveByConversation).toHaveBeenCalledWith({ + channel: "telegram", + accountId: "default", + conversationId: "-1001234567890", + }); + const dispatchCall = ( + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< + [{ ctx?: { CommandTargetSessionKey?: string; OriginatingTo?: string } }] + > + )[0]?.[0]; + expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe("agent:codex-acp:session-group"); + expect(dispatchCall?.ctx?.OriginatingTo).toBe("telegram:-1001234567890"); + const sessionMetaCall = ( + sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< + [{ sessionKey?: string }] + > + )[0]?.[0]; + expect(sessionMetaCall?.sessionKey).toBe("agent:codex-acp:session-group"); + expect(sessionBindingMocks.touch).toHaveBeenCalledWith("default:-1001234567890", undefined); + }); + + it.each(["new", "reset"] as const)( + "preserves the topic-qualified origin target for native /%s in forum topics", + async (commandName) => { + const { handler } = registerAndResolveCommandHandler({ + commandName, + cfg: {}, + allowFrom: ["200"], + groupAllowFrom: ["200"], + }); + await handler(createTelegramTopicCommandContext()); + + const dispatchCall = ( + replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< + [ + { + ctx?: { + CommandTargetSessionKey?: string; + MessageThreadId?: number; + OriginatingTo?: string; + }; + }, + ] + > + )[0]?.[0]; + expectRecordFields( + dispatchCall?.ctx, + { + CommandTargetSessionKey: "agent:main:telegram:group:-1001234567890:topic:42", + MessageThreadId: 42, + OriginatingTo: "telegram:-1001234567890:topic:42", + }, + "topic dispatch context", + ); + }, + ); + + it("aborts native command dispatch when configured ACP topic binding cannot initialize", async () => { + const boundSessionKey = "agent:codex:acp:binding:telegram:default:feedface"; + persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => + createConfiguredBindingRoute( + { + ...route, + sessionKey: boundSessionKey, + agentId: "codex", + matchedBy: "binding.channel", + }, + createConfiguredAcpTopicBinding(boundSessionKey), + ), + ); + persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ + ok: false, + error: "gateway unavailable", + }); + + const { handler, sendMessage } = registerAndResolveStatusHandler({ + cfg: {}, + allowFrom: ["200"], + groupAllowFrom: ["200"], + }); + await handler(createTelegramTopicCommandContext()); + + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + expectSendMessageCall({ + sendMessage, + chatId: -1001234567890, + text: "Configured ACP binding is unavailable right now. Please try again.", + optionFields: { message_thread_id: 42 }, + label: "unavailable ACP binding", + }); + }); + + it("keeps /new blocked in ACP-bound Telegram topics when sender is unauthorized", async () => { + const boundSessionKey = "agent:codex:acp:binding:telegram:default:feedface"; + persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => + createConfiguredBindingRoute( + { + ...route, + sessionKey: boundSessionKey, + agentId: "codex", + matchedBy: "binding.channel", + }, + createConfiguredAcpTopicBinding(boundSessionKey), + ), + ); + persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ ok: true }); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "new", + cfg: {}, + allowFrom: [], + groupAllowFrom: [], + }); + await handler(createTelegramTopicCommandContext()); + + expectUnauthorizedNewCommandBlocked(sendMessage); + }); + + it("keeps /new blocked for unbound Telegram topics when sender is unauthorized", async () => { + persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => + createConfiguredBindingRoute(route, null), + ); + + const { handler, sendMessage } = registerAndResolveCommandHandler({ + commandName: "new", + cfg: {}, + allowFrom: [], + groupAllowFrom: [], + }); + await handler(createTelegramTopicCommandContext()); + + expectUnauthorizedNewCommandBlocked(sendMessage); + }); +}); diff --git a/extensions/telegram/src/bot-native-command-dispatch.test-support.ts b/extensions/telegram/src/bot-native-command-dispatch.test-support.ts new file mode 100644 index 000000000000..09b758694fcb --- /dev/null +++ b/extensions/telegram/src/bot-native-command-dispatch.test-support.ts @@ -0,0 +1,107 @@ +import type { ResolvedAgentRoute } from "openclaw/plugin-sdk/routing"; + +export function createConfiguredAcpTopicBinding(boundSessionKey: string) { + return { + spec: { + channel: "telegram", + accountId: "default", + conversationId: "-1001234567890:topic:42", + parentConversationId: "-1001234567890", + agentId: "codex", + mode: "persistent", + }, + record: { + bindingId: "config:acp:telegram:default:-1001234567890:topic:42", + targetSessionKey: boundSessionKey, + targetKind: "session", + conversation: { + channel: "telegram", + accountId: "default", + conversationId: "-1001234567890:topic:42", + parentConversationId: "-1001234567890", + }, + status: "active", + boundAt: 0, + }, + } as const; +} + +export function createConfiguredBindingRoute( + route: ResolvedAgentRoute, + binding: ReturnType | null, +) { + return { + bindingResolution: binding + ? { + conversation: binding.record.conversation, + compiledBinding: { + channel: "telegram" as const, + binding: { + type: "acp" as const, + agentId: binding.spec.agentId, + match: { + channel: "telegram", + accountId: binding.spec.accountId, + peer: { + kind: "group" as const, + id: binding.spec.conversationId, + }, + }, + acp: { + mode: binding.spec.mode, + }, + }, + bindingConversationId: binding.spec.conversationId, + target: { + conversationId: binding.spec.conversationId, + ...(binding.spec.parentConversationId + ? { parentConversationId: binding.spec.parentConversationId } + : {}), + }, + agentId: binding.spec.agentId, + provider: { + compileConfiguredBinding: () => ({ + conversationId: binding.spec.conversationId, + ...(binding.spec.parentConversationId + ? { parentConversationId: binding.spec.parentConversationId } + : {}), + }), + matchInboundConversation: () => ({ + conversationId: binding.spec.conversationId, + ...(binding.spec.parentConversationId + ? { parentConversationId: binding.spec.parentConversationId } + : {}), + }), + }, + targetFactory: { + driverId: "acp" as const, + materialize: () => ({ + record: binding.record, + statefulTarget: { + kind: "stateful" as const, + driverId: "acp" as const, + sessionKey: binding.record.targetSessionKey, + agentId: binding.spec.agentId, + }, + }), + }, + }, + match: { + conversationId: binding.spec.conversationId, + ...(binding.spec.parentConversationId + ? { parentConversationId: binding.spec.parentConversationId } + : {}), + }, + record: binding.record, + statefulTarget: { + kind: "stateful" as const, + driverId: "acp" as const, + sessionKey: binding.record.targetSessionKey, + agentId: binding.spec.agentId, + }, + } + : null, + ...(binding ? { boundSessionKey: binding.record.targetSessionKey } : {}), + route, + }; +} diff --git a/extensions/telegram/src/bot-native-command-dispatch.ts b/extensions/telegram/src/bot-native-command-dispatch.ts new file mode 100644 index 000000000000..c614b9171729 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-dispatch.ts @@ -0,0 +1,699 @@ +// Telegram plugin module implements native command admission and dispatch behavior. +import type { Bot, Context } from "grammy"; +import { + isChannelPartialDeliveryError, + type ChannelInboundTurnPlan, +} from "openclaw/plugin-sdk/channel-inbound"; +import { resolveChannelStreamingBlockEnabled } from "openclaw/plugin-sdk/channel-outbound"; +import { resolveNativeCommandSessionTargets } from "openclaw/plugin-sdk/command-auth-native"; +import type { + ChannelGroupPolicy, + OpenClawConfig, + TelegramAccountConfig, +} from "openclaw/plugin-sdk/config-contracts"; +import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime"; +import { resolveMarkdownTableMode } from "openclaw/plugin-sdk/markdown-table-runtime"; +import { + PLUGIN_COMMAND_DISPATCH, + type PluginCommandCatalogDecision, +} from "openclaw/plugin-sdk/plugin-command-runtime"; +import { danger, logVerbose, type RuntimeEnv } from "openclaw/plugin-sdk/runtime-env"; +import { resolveStorePath } from "openclaw/plugin-sdk/session-store-runtime"; +import { expandTelegramAllowFromWithAccessGroups } from "./access-groups.js"; +import { resolveTelegramAccount } from "./accounts.js"; +import { withTelegramApiErrorLogging } from "./api-logging.js"; +import { normalizeDmAllowFromWithStore, resolveTelegramEffectiveDmPolicy } from "./bot-access.js"; +import type { TelegramBotDeps } from "./bot-deps.js"; +import type { TelegramResolvedGroupConfig } from "./bot-handlers.types.js"; +import { resolveTelegramMessageTurnSettings } from "./bot-message.js"; +import { + defaultTelegramNativeCommandDeps, + type TelegramNativeCommandDeps, +} from "./bot-native-command-deps.runtime.js"; +import type { TelegramBotOptions } from "./bot.types.js"; +import { + buildSenderName, + buildTelegramGroupFrom, + buildTelegramRoutingTarget, + buildTelegramThreadParams, + extractTelegramForumFlag, + isTelegramCommandsAllowFromConfigured, + resolveTelegramBotHasTopicsEnabled, + resolveTelegramCommandAuthorization, + resolveTelegramForumFlag, + resolveTelegramGroupAllowFromContext, + resolveTelegramMessageThreadSpec, + resolveTelegramThreadSpec, +} from "./bot/helpers.js"; +import type { TelegramGetChat } from "./bot/types.js"; +import { + resolveTelegramConversationRoute, + resolveTelegramTargetSession, +} from "./conversation-route.js"; +import { shouldSuppressLocalTelegramExecApprovalPrompt } from "./exec-approvals.js"; +import { + evaluateTelegramGroupBaseAccess, + evaluateTelegramGroupPolicyAccess, +} from "./group-access.js"; +import { + resolveTelegramDirectToolPolicy, + resolveTelegramGroupPromptSettings, +} from "./group-config-helpers.js"; +import { resolveTelegramCommandIngressAuthorization } from "./ingress.js"; +import { getTopicName, resolveTopicNameCacheScope } from "./topic-name-cache.js"; + +const EMPTY_RESPONSE_FALLBACK = "No response generated. Please try again."; +const NON_PLUGIN_COMMAND_DISPATCH = Object.freeze({ + kind: "non-plugin", +}) satisfies PluginCommandCatalogDecision; + +const loadTelegramNativeCommandDeliveryRuntime = createLazyRuntimeModule( + () => import("./bot-native-commands.delivery.runtime.js"), +); +const loadTelegramNativeCommandRuntime = createLazyRuntimeModule( + () => import("./bot-native-commands.runtime.js"), +); + +type TelegramNativeCommandRuntime = Awaited>; +type TelegramNativeCommandDeliveryRuntime = Awaited< + ReturnType +>; +type DeliveryBaseOptions = Omit< + Parameters[0], + "replies" | "silent" +>; + +export type TelegramCommandExecutorParams = { + botUser: Context["me"]; + msg: NonNullable; + rawText: string; + bot: Bot; + runtime: RuntimeEnv; + accountId: string; + mediaMaxBytes?: number; + resolveGroupPolicy: (chatId: string | number, cfg: OpenClawConfig) => ChannelGroupPolicy; + resolveTelegramGroupConfig: ( + chatId: string | number, + messageThreadId: number | undefined, + cfg: OpenClawConfig, + ) => TelegramResolvedGroupConfig; + telegramDeps?: TelegramNativeCommandDeps; + opts: Pick< + TelegramBotOptions, + "token" | "botInfo" | "allowFrom" | "groupAllowFrom" | "replyToMode" | "accountAbortSignal" + >; +}; + +type TelegramCommandAuthResult = NonNullable< + Awaited> +>; + +export type TelegramCommandDispatch = TelegramCommandExecutorParams & + TelegramCommandAuthResult & { + telegramDeps: TelegramNativeCommandDeps; + runtimeCfg: OpenClawConfig; + runtimeTelegramCfg: TelegramAccountConfig; + turnSettings: ReturnType; + threadSpec: ReturnType; + threadParams: ReturnType; + route: ReturnType["route"]; + mediaLocalRoots: readonly string[] | undefined; + targetSessionKey: string; + nativeCommandRuntime: TelegramNativeCommandRuntime; + buildDeliveryBaseOptions: (params?: { + sessionKeyForInternalHooks?: string; + policySessionKey?: string; + }) => DeliveryBaseOptions; + loadDeliveryRuntime: () => Promise; + }; + +async function resolveTelegramNativeCommandThreadContext(params: { + msg: NonNullable; + bot: Bot; +}) { + const { msg, bot } = params; + const chatId = msg.chat.id; + const isGroup = msg.chat.type === "group" || msg.chat.type === "supergroup"; + const getChat = + typeof bot.api.getChat === "function" + ? (bot.api.getChat.bind(bot.api) as TelegramGetChat) + : undefined; + const isForum = + msg.chat.is_direct_messages === true + ? false + : await resolveTelegramForumFlag({ + chatId, + chatType: msg.chat.type, + isGroup, + isForum: extractTelegramForumFlag(msg.chat), + isTopicMessage: msg.is_topic_message, + getChat, + }); + const threadSpec = resolveTelegramMessageThreadSpec(msg, isForum); + return { + chatId, + isGroup, + isForum, + threadSpec, + threadParams: buildTelegramThreadParams(threadSpec), + }; +} + +async function resolveTelegramCommandAuth(params: { + msg: NonNullable; + bot: Bot; + cfg: OpenClawConfig; + accountId: string; + telegramCfg: TelegramAccountConfig; + readChannelAllowFromStore: TelegramBotDeps["readChannelAllowFromStore"]; + allowFrom?: Array; + groupAllowFrom?: Array; + resolveGroupPolicy: TelegramCommandExecutorParams["resolveGroupPolicy"]; + resolveTelegramGroupConfig: TelegramCommandExecutorParams["resolveTelegramGroupConfig"]; + requireAuth: boolean; +}) { + const { msg, bot, cfg, accountId, telegramCfg, requireAuth } = params; + const { chatId, isGroup, isForum, threadSpec, threadParams } = + await resolveTelegramNativeCommandThreadContext({ msg, bot }); + const senderId = msg.from?.id ? String(msg.from.id) : ""; + const senderUsername = msg.from?.username ?? ""; + const commandsAllowFromConfigured = isTelegramCommandsAllowFromConfigured(cfg); + const preContextCommandsAllowFromAccess = commandsAllowFromConfigured + ? resolveTelegramCommandAuthorization({ + cfg, + accountId, + chatId, + isGroup, + senderId, + senderUsername, + }) + : null; + const groupAllowContext = await resolveTelegramGroupAllowFromContext({ + cfg, + chatId, + accountId, + dmPolicy: telegramCfg.dmPolicy, + allowFrom: params.allowFrom, + senderId, + isGroup, + threadSpec, + groupAllowFrom: params.groupAllowFrom, + skipPairingStoreRead: Boolean(preContextCommandsAllowFromAccess?.isAuthorizedSender), + readChannelAllowFromStore: params.readChannelAllowFromStore, + resolveTelegramGroupConfig: params.resolveTelegramGroupConfig, + }); + const { + resolvedThreadId, + dmThreadId, + storeAllowFrom, + groupConfig, + topicConfig, + groupAllowOverride, + effectiveGroupAllow, + hasGroupAllowOverride, + } = groupAllowContext; + const effectiveDmPolicy = resolveTelegramEffectiveDmPolicy({ + isGroup, + groupConfig, + dmPolicy: telegramCfg.dmPolicy, + }); + const requireTopic = + !isGroup && groupConfig && "requireTopic" in groupConfig ? groupConfig.requireTopic : undefined; + if (!isGroup && requireTopic === true && dmThreadId == null) { + logVerbose(`Blocked telegram command in DM ${chatId}: requireTopic=true but no topic present`); + return null; + } + const commandsAllowFromAccess = commandsAllowFromConfigured + ? resolveTelegramCommandAuthorization({ + cfg, + accountId, + chatId, + isGroup, + resolvedThreadId, + senderId, + senderUsername, + }) + : null; + const ownerAccess = resolveTelegramCommandAuthorization({ + cfg, + accountId, + chatId, + isGroup, + resolvedThreadId, + senderId, + senderUsername, + }); + const sendAuthMessage = async (text: string) => { + await withTelegramApiErrorLogging({ + operation: "sendMessage", + fn: () => bot.api.sendMessage(chatId, text, threadParams ?? {}), + }); + return null; + }; + const rejectNotAuthorized = async () => + await sendAuthMessage("You are not authorized to use this command."); + + const baseAccess = evaluateTelegramGroupBaseAccess({ + isGroup, + groupConfig, + topicConfig, + hasGroupAllowOverride, + effectiveGroupAllow, + senderId, + senderUsername, + enforceAllowOverride: requireAuth, + requireSenderForAllowOverride: true, + }); + if (!baseAccess.allowed) { + if (baseAccess.reason === "group-disabled") { + logVerbose(`Blocked telegram command in group ${chatId} (group disabled)`); + return null; + } + if (baseAccess.reason === "topic-disabled") { + logVerbose( + `Blocked telegram command in topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`, + ); + return null; + } + return await rejectNotAuthorized(); + } + + const policyAccess = evaluateTelegramGroupPolicyAccess({ + isGroup, + chatId, + cfg, + telegramCfg, + topicConfig, + groupConfig, + effectiveGroupAllow, + senderId, + senderUsername, + resolveGroupPolicy: params.resolveGroupPolicy, + enforcePolicy: true, + enforceAllowlistAuthorization: requireAuth && !commandsAllowFromConfigured, + allowEmptyAllowlistEntries: true, + requireSenderForAllowlistAuthorization: true, + checkChatAllowlist: true, + }); + if (!policyAccess.allowed) { + if (policyAccess.reason === "group-policy-disabled") { + logVerbose("Blocked telegram command (groupPolicy: disabled)"); + return null; + } + if ( + policyAccess.reason === "group-policy-allowlist-no-sender" || + policyAccess.reason === "group-policy-allowlist-unauthorized" + ) { + return await rejectNotAuthorized(); + } + if (policyAccess.reason === "group-chat-not-allowed") { + logVerbose(`Blocked telegram command in group ${chatId} (group not allowed)`); + return null; + } + } + + const expandedDmAllowFrom = await expandTelegramAllowFromWithAccessGroups({ + cfg, + allowFrom: groupAllowOverride ?? params.allowFrom, + accountId, + senderId, + }); + const dmAllow = normalizeDmAllowFromWithStore({ + allowFrom: expandedDmAllowFrom, + storeAllowFrom: isGroup ? [] : storeAllowFrom, + dmPolicy: effectiveDmPolicy, + }); + const commandAuthorized = commandsAllowFromConfigured + ? Boolean(commandsAllowFromAccess?.isAuthorizedSender) + : ( + await resolveTelegramCommandIngressAuthorization({ + accountId, + cfg, + dmPolicy: effectiveDmPolicy, + isGroup, + chatId, + resolvedThreadId, + senderId, + effectiveDmAllow: dmAllow, + effectiveGroupAllow, + ownerAccess, + eventKind: "native-command", + }) + ).authorized; + if (requireAuth && !commandAuthorized) { + return await rejectNotAuthorized(); + } + return { + chatId, + isGroup, + isForum, + resolvedThreadId, + senderId, + senderUsername, + groupConfig, + topicConfig, + commandAuthorized, + senderIsOwner: ownerAccess.senderIsOwner, + }; +} + +export async function prepareTelegramCommandDispatch( + params: TelegramCommandExecutorParams & { requireAuth: boolean }, +): Promise { + const telegramDeps = params.telegramDeps ?? defaultTelegramNativeCommandDeps; + const runtimeCfg = telegramDeps.getRuntimeConfig(); + const runtimeTelegramCfg = resolveTelegramAccount({ + cfg: runtimeCfg, + accountId: params.accountId, + }).config; + const turnSettings = resolveTelegramMessageTurnSettings({ + accountId: params.accountId, + cfg: runtimeCfg, + telegramCfg: runtimeTelegramCfg, + opts: params.opts, + }); + const auth = await resolveTelegramCommandAuth({ + msg: params.msg, + bot: params.bot, + cfg: runtimeCfg, + accountId: params.accountId, + telegramCfg: runtimeTelegramCfg, + readChannelAllowFromStore: telegramDeps.readChannelAllowFromStore, + allowFrom: turnSettings.allowFrom, + groupAllowFrom: turnSettings.groupAllowFrom, + resolveGroupPolicy: params.resolveGroupPolicy, + resolveTelegramGroupConfig: params.resolveTelegramGroupConfig, + requireAuth: params.requireAuth, + }); + if (!auth) { + return null; + } + const threadSpec = resolveTelegramMessageThreadSpec(params.msg, auth.isForum); + const { route, bindingMode } = resolveTelegramConversationRoute({ + cfg: runtimeCfg, + accountId: params.accountId, + chatId: auth.chatId, + isGroup: auth.isGroup, + resolvedThreadId: auth.resolvedThreadId, + replyThreadId: threadSpec.id, + senderId: auth.senderId, + topicAgentId: auth.topicConfig?.agentId, + }); + const nativeCommandRuntime = await loadTelegramNativeCommandRuntime(); + if (bindingMode.kind === "configured") { + const ensured = await nativeCommandRuntime.ensureConfiguredBindingRouteReady({ + cfg: runtimeCfg, + bindingResolution: bindingMode.binding, + }); + if (!ensured.ok) { + logVerbose( + `telegram native command: configured ACP binding unavailable for topic ${bindingMode.binding.record.conversation.conversationId}: ${ensured.error}`, + ); + await withTelegramApiErrorLogging({ + operation: "sendMessage", + runtime: params.runtime, + fn: () => + params.bot.api.sendMessage( + auth.chatId, + "Configured ACP binding is unavailable right now. Please try again.", + buildTelegramThreadParams(threadSpec) ?? {}, + ), + }); + return null; + } + } + const mediaLocalRoots = nativeCommandRuntime.getAgentScopedMediaLocalRoots( + runtimeCfg, + route.agentId, + ); + const tableMode = resolveMarkdownTableMode({ + cfg: runtimeCfg, + channel: "telegram", + accountId: route.accountId, + supportsBlockTables: true, + }); + const chunkMode = nativeCommandRuntime.resolveChunkMode(runtimeCfg, "telegram", route.accountId); + const targetSessionKey = resolveTelegramTargetSession({ + cfg: runtimeCfg, + route, + chatId: auth.chatId, + isGroup: auth.isGroup, + senderId: auth.senderId, + dmThreadId: threadSpec.scope === "dm" ? threadSpec.id : undefined, + botHasTopicsEnabled: resolveTelegramBotHasTopicsEnabled(params.botUser), + }); + const buildDeliveryBaseOptions = (keys?: { + sessionKeyForInternalHooks?: string; + policySessionKey?: string; + }): DeliveryBaseOptions => ({ + cfg: runtimeCfg, + chatId: String(auth.chatId), + accountId: route.accountId, + sessionKeyForInternalHooks: keys?.sessionKeyForInternalHooks, + policySessionKey: keys?.policySessionKey, + mirrorIsGroup: auth.isGroup, + mirrorGroupId: auth.isGroup ? String(auth.chatId) : undefined, + token: params.opts.token, + runtime: params.runtime, + bot: params.bot, + mediaLocalRoots, + mediaMaxBytes: params.mediaMaxBytes, + replyToMode: turnSettings.replyToMode, + textLimit: turnSettings.textLimit, + thread: threadSpec, + tableMode, + chunkMode, + linkPreview: runtimeTelegramCfg.linkPreview, + richMessages: runtimeTelegramCfg.richMessages, + }); + return { + ...params, + telegramDeps, + runtimeCfg, + runtimeTelegramCfg, + turnSettings, + ...auth, + threadSpec, + threadParams: buildTelegramThreadParams(threadSpec), + route, + mediaLocalRoots, + targetSessionKey, + nativeCommandRuntime, + buildDeliveryBaseOptions, + loadDeliveryRuntime: loadTelegramNativeCommandDeliveryRuntime, + }; +} + +export async function dispatchTelegramBuiltinTurn(params: { + dispatch: TelegramCommandDispatch; + prompt: string; + commandArgs?: import("openclaw/plugin-sdk/command-auth-native").CommandArgs; +}): Promise { + const { dispatch } = params; + const { skillFilter, groupSystemPrompt } = resolveTelegramGroupPromptSettings({ + groupConfig: dispatch.groupConfig, + topicConfig: dispatch.topicConfig, + }); + const { sessionKey: commandSessionKey, commandTargetSessionKey } = + resolveNativeCommandSessionTargets({ + agentId: dispatch.route.agentId, + sessionPrefix: "telegram:slash", + userId: String(dispatch.senderId || dispatch.chatId), + targetSessionKey: dispatch.targetSessionKey, + }); + let topicName: string | undefined; + if (dispatch.isForum && dispatch.resolvedThreadId != null) { + try { + const storePath = resolveStorePath(dispatch.runtimeCfg.session?.store, { + agentId: dispatch.route.accountId, + }); + topicName = await getTopicName( + dispatch.chatId, + dispatch.resolvedThreadId, + resolveTopicNameCacheScope(storePath), + ); + } catch { + // best-effort: topic name is supplementary metadata + } + } + const conversationLabel = dispatch.isGroup + ? dispatch.msg.chat.title + ? `${dispatch.msg.chat.title} id:${dispatch.chatId}` + : `group:${dispatch.chatId}` + : (buildSenderName(dispatch.msg) ?? String(dispatch.senderId || dispatch.chatId)); + const ctxPayload = dispatch.nativeCommandRuntime.finalizeInboundContext({ + Body: params.prompt, + BodyForAgent: params.prompt, + RawBody: params.prompt, + CommandBody: params.prompt, + CommandArgs: params.commandArgs, + From: dispatch.isGroup + ? buildTelegramGroupFrom(dispatch.chatId, dispatch.resolvedThreadId) + : `telegram:${dispatch.chatId}`, + To: `slash:${dispatch.senderId || dispatch.chatId}`, + ChatType: dispatch.isGroup ? "group" : "direct", + ConversationToolPolicy: dispatch.isGroup + ? undefined + : resolveTelegramDirectToolPolicy({ + directConfig: dispatch.groupConfig, + senderId: dispatch.senderId, + senderName: buildSenderName(dispatch.msg), + senderUsername: dispatch.senderUsername, + }), + ConversationLabel: conversationLabel, + GroupSubject: dispatch.isGroup ? (dispatch.msg.chat.title ?? undefined) : undefined, + GroupSystemPrompt: + dispatch.isGroup || (!dispatch.isGroup && dispatch.groupConfig) + ? groupSystemPrompt + : undefined, + SenderName: buildSenderName(dispatch.msg), + SenderId: dispatch.senderId || undefined, + SenderUsername: dispatch.senderUsername || undefined, + Surface: "telegram", + Provider: "telegram", + MessageSid: String(dispatch.msg.message_id), + Timestamp: dispatch.msg.date ? dispatch.msg.date * 1000 : undefined, + WasMentioned: true, + CommandAuthorized: dispatch.commandAuthorized, + CommandTurn: { + kind: "native" as const, + source: "native" as const, + authorized: dispatch.commandAuthorized, + body: params.prompt, + }, + CommandSource: "native" as const, + SessionKey: commandSessionKey, + AccountId: dispatch.route.accountId, + CommandTargetSessionKey: commandTargetSessionKey, + MessageThreadId: dispatch.threadSpec.id, + IsForum: dispatch.isForum, + TopicName: dispatch.isForum && topicName ? topicName : undefined, + OriginatingChannel: "telegram" as const, + OriginatingTo: buildTelegramRoutingTarget(dispatch.chatId, dispatch.threadSpec), + }); + const deliveryState = { delivered: false, skippedNonSilent: 0, failedNonSilent: 0 }; + let finalReplyOutcome: "accepted" | "failed" | "suppressed" | undefined; + let recordSessionMetaTask: Promise | undefined; + const deliveryBaseOptions = dispatch.buildDeliveryBaseOptions({ + sessionKeyForInternalHooks: commandSessionKey, + policySessionKey: commandTargetSessionKey, + }); + const { deliverReplies } = await dispatch.loadDeliveryRuntime(); + const turnPlan: ChannelInboundTurnPlan<"provider_message_sending"> = { + cfg: dispatch.runtimeCfg, + channel: "telegram", + accountId: dispatch.route.accountId, + route: { agentId: dispatch.route.agentId, sessionKey: commandSessionKey }, + ctxPayload, + record: { + sessionKey: commandTargetSessionKey, + trackSessionMetaTask: (task) => { + recordSessionMetaTask = task; + }, + onRecordError: (error) => + dispatch.runtime.error?.( + danger(`telegram slash: failed updating session meta: ${String(error)}`), + ), + }, + afterRecord: async () => { + await recordSessionMetaTask; + }, + replyPipeline: {}, + dispatcherOptions: { + beforeDeliver: async (payload) => payload, + onSkip: (_payload, info) => { + if (info.reason !== "silent") { + deliveryState.skippedNonSilent += 1; + } + }, + }, + delivery: { + deliverWithProviderMessageSending: async (payload, info) => { + if ( + shouldSuppressLocalTelegramExecApprovalPrompt({ + cfg: dispatch.runtimeCfg, + accountId: dispatch.route.accountId, + payload, + }) + ) { + deliveryState.delivered = true; + return { visibleReplySent: false, suppression: { reason: "no_visible_result" } }; + } + const targetedPayload = payload.replyToId + ? payload + : { ...payload, replyToId: String(dispatch.msg.message_id) }; + const result = await deliverReplies({ + replies: [ + info.bindPendingFinalDelivery + ? info.bindPendingFinalDelivery(targetedPayload) + : targetedPayload, + ], + ...deliveryBaseOptions, + silent: + dispatch.runtimeTelegramCfg.silentErrorReplies === true && payload.isError === true, + onPlatformSendDispatch: info.onPlatformSendDispatch, + }); + if (result.delivered) { + deliveryState.delivered = true; + } + return result.delivered + ? { visibleReplySent: true } + : { visibleReplySent: false, suppression: { reason: "no_visible_result" as const } }; + }, + onDelivered: (_payload, info, result) => { + const reason = result?.suppression?.reason; + if (info.kind === "final" && result?.visibleReplySent) { + finalReplyOutcome = "accepted"; + } + if ( + info.kind === "final" && + finalReplyOutcome !== "failed" && + (reason === "cancelled_by_reply_payload_sending_hook" || + reason === "empty_after_reply_payload_sending_hook") + ) { + finalReplyOutcome = "suppressed"; + } + }, + onError: (error, info) => { + deliveryState.failedNonSilent += 1; + const partialDelivery = isChannelPartialDeliveryError(error); + if (partialDelivery) { + deliveryState.delivered = true; + logVerbose("telegram slash reply partially delivered before failure"); + } + if (info.kind === "final") { + finalReplyOutcome = partialDelivery ? "accepted" : "failed"; + } + dispatch.runtime.error?.( + danger(`telegram slash ${info.kind} reply failed: ${String(error)}`), + ); + }, + }, + replyOptions: { + skillFilter, + disableBlockStreaming: (() => { + const enabled = resolveChannelStreamingBlockEnabled(dispatch.runtimeTelegramCfg); + return typeof enabled === "boolean" ? !enabled : undefined; + })(), + [PLUGIN_COMMAND_DISPATCH]: NON_PLUGIN_COMMAND_DISPATCH, + }, + }; + const turnResult = await ( + dispatch.telegramDeps.dispatchChannelInboundTurn ?? + defaultTelegramNativeCommandDeps.dispatchChannelInboundTurn + )(turnPlan); + if ( + !deliveryState.delivered && + finalReplyOutcome !== "suppressed" && + (deliveryState.skippedNonSilent > 0 || deliveryState.failedNonSilent > 0) && + (!turnResult.dispatched || + turnResult.dispatchResult.sourceReplyDeliveryMode !== "message_tool_only" || + deliveryState.failedNonSilent > 0) + ) { + await deliverReplies({ + replies: [{ text: EMPTY_RESPONSE_FALLBACK }], + ...deliveryBaseOptions, + }); + } + return false; +} diff --git a/extensions/telegram/src/bot-native-command-executors.test-support.ts b/extensions/telegram/src/bot-native-command-executors.test-support.ts new file mode 100644 index 000000000000..8a3b5a9722f6 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-executors.test-support.ts @@ -0,0 +1,580 @@ +export { createChannelPartialDeliveryError } from "openclaw/plugin-sdk/channel-inbound"; +import { + createEmptyPluginRegistry, + withPluginRuntimeRegistryScope, +} from "openclaw/plugin-sdk/channel-test-helpers"; +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +export { createDeferred } from "openclaw/plugin-sdk/extension-shared"; +import { getAgentScopedMediaLocalRoots } from "openclaw/plugin-sdk/media-runtime"; +import { registerPluginCommand } from "openclaw/plugin-sdk/plugin-runtime"; +import { resolveChunkMode } from "openclaw/plugin-sdk/reply-dispatch-runtime"; +import { resolveThreadSessionKeys } from "openclaw/plugin-sdk/routing"; +// Telegram tests cover bot native commands.session meta plugin behavior. +import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures"; +import { expect, vi } from "vitest"; +import type { RegisterTelegramHandlerParams } from "./bot-handlers.types.js"; +import type { TelegramNativeCommandDeps } from "./bot-native-command-deps.runtime.js"; +import { createConfiguredBindingRoute } from "./bot-native-command-dispatch.test-support.js"; +import { + createNativeCommandTestParams, + createTelegramPrivateCommandContext, + type NativeCommandTestParams, +} from "./bot-native-commands.fixture-test-support.js"; +export { runWithTelegramUpdateProcessingFrame } from "./bot-processing-outcome.js"; + +// Shared executor test harness; each importing suite resets the state before use. + +type ResolveConfiguredBindingRouteFn = + typeof import("openclaw/plugin-sdk/conversation-runtime").resolveConfiguredBindingRoute; +type EnsureConfiguredBindingRouteReadyFn = + typeof import("openclaw/plugin-sdk/conversation-runtime").ensureConfiguredBindingRouteReady; +type DispatchReplyWithBufferedBlockDispatcherFn = + typeof import("openclaw/plugin-sdk/reply-dispatch-runtime").dispatchReplyWithBufferedBlockDispatcher; +export type DispatchReplyWithBufferedBlockDispatcherParams = + Parameters[0]; +type DispatchReplyWithBufferedBlockDispatcherResult = Awaited< + ReturnType +>; +type DispatchChannelInboundTurnFn = + typeof import("openclaw/plugin-sdk/channel-inbound").dispatchChannelInboundTurn; +type ResolveCommandArgMenuFn = + typeof import("openclaw/plugin-sdk/command-auth-native").resolveCommandArgMenu; +type DeliverRepliesFn = typeof import("./bot/delivery.js").deliverReplies; +type LoadModelCatalogFn = typeof import("openclaw/plugin-sdk/agent-runtime").loadModelCatalog; +type ResolveDefaultModelForAgentFn = + typeof import("openclaw/plugin-sdk/agent-runtime").resolveDefaultModelForAgent; + +export const dispatchReplyResult: DispatchReplyWithBufferedBlockDispatcherResult = { + queuedFinal: false, + counts: {} as DispatchReplyWithBufferedBlockDispatcherResult["counts"], +}; + +const persistentBindingMocks = vi.hoisted(() => ({ + resolveConfiguredBindingRoute: vi.fn(({ route }) => ({ + bindingResolution: null, + route, + })), + ensureConfiguredBindingRouteReady: vi.fn(async () => ({ + ok: true, + })), +})); +const sessionMocks = vi.hoisted(() => ({ + getSessionEntry: vi.fn(), + sessionStoreEntries: vi.fn(), + recordSessionMetaFromInbound: vi.fn(), + resolveStorePath: vi.fn(), + updateSessionStoreEntry: vi.fn(), +})); +const commandAuthMocks = vi.hoisted(() => ({ + resolveCommandArgMenu: vi.fn(), +})); +const agentRuntimeMocks = vi.hoisted(() => ({ + loadModelCatalog: vi.fn(async () => [ + { + provider: "openai", + id: "gpt-5.5", + name: "GPT-5.5", + reasoning: true, + }, + ]), + resolveDefaultModelForAgent: vi.fn(), +})); +const pluginRuntimeMocks = vi.hoisted(() => ({ + executePluginCommand: vi.fn(async (_params?: unknown) => ({ text: "ok" })), +})); +const replyMocks = vi.hoisted(() => ({ + dispatchReplyWithBufferedBlockDispatcher: vi.fn( + async () => dispatchReplyResult, + ), +})); +const deliveryMocks = vi.hoisted(() => ({ + deliverReplies: vi.fn(async () => ({ delivered: true })), +})); +export const dispatchChannelInboundTurnMock = vi.fn(async (plan) => { + const recordTask = sessionMocks.recordSessionMetaFromInbound({ + storePath: sessionMocks.resolveStorePath(plan.cfg.session?.store, { + agentId: plan.route.agentId, + }), + sessionKey: plan.record?.sessionKey ?? plan.ctxPayload.SessionKey ?? plan.route.sessionKey, + ctx: plan.ctxPayload, + }); + const trackedRecordTask = Promise.resolve(recordTask).catch((error: unknown) => + plan.record?.onRecordError?.(error), + ); + plan.record?.trackSessionMetaTask?.(trackedRecordTask); + await plan.afterRecord?.(); + const deliver = async ( + payload: Parameters< + DispatchReplyWithBufferedBlockDispatcherParams["dispatcherOptions"]["deliver"] + >[0], + info: Parameters< + DispatchReplyWithBufferedBlockDispatcherParams["dispatcherOptions"]["deliver"] + >[1], + ) => { + const providerInfo = { + ...info, + onPlatformSendDispatch: async () => undefined, + }; + const result = + "deliverWithProviderMessageSending" in plan.delivery + ? await plan.delivery.deliverWithProviderMessageSending(payload, providerInfo) + : await plan.delivery.deliver(payload, info); + await plan.delivery.onDelivered?.(payload, info, result); + return result; + }; + const dispatchResult = await replyMocks.dispatchReplyWithBufferedBlockDispatcher({ + ctx: plan.ctxPayload, + cfg: plan.cfg, + dispatcherOptions: { + ...plan.dispatcherOptions, + deliver, + onError: plan.delivery.onError, + }, + replyOptions: plan.replyOptions, + }); + return { + admission: { kind: "dispatch" }, + dispatched: true, + ctxPayload: plan.ctxPayload, + routeSessionKey: plan.route.sessionKey, + dispatchResult, + }; +}); +const sessionBindingMocks = vi.hoisted(() => ({ + resolveByConversation: vi.fn< + (ref: unknown) => { bindingId: string; targetSessionKey: string } | null + >(() => null), + touch: vi.fn(), +})); +const conversationStoreMocks = vi.hoisted(() => ({ + readChannelAllowFromStore: vi.fn(async () => []), + upsertChannelPairingRequest: vi.fn(async () => ({ code: "PAIRCODE", created: true })), +})); + +export const executorTestMocks = { + agentRuntimeMocks, + commandAuthMocks, + conversationStoreMocks, + deliveryMocks, + persistentBindingMocks, + pluginRuntimeMocks, + replyMocks, + sessionBindingMocks, + sessionMocks, +}; + +vi.mock("openclaw/plugin-sdk/conversation-runtime", async () => { + const actual = await vi.importActual( + "openclaw/plugin-sdk/conversation-runtime", + ); + return { + ...actual, + resolveConfiguredBindingRoute: persistentBindingMocks.resolveConfiguredBindingRoute, + resolveRuntimeConversationBindingRoute: ( + params: Parameters[0], + ) => { + const conversation = + "conversation" in params + ? params.conversation + : { + channel: params.channel, + accountId: params.accountId, + conversationId: params.conversationId, + parentConversationId: params.parentConversationId, + }; + const bindingRecord = sessionBindingMocks.resolveByConversation(conversation); + const boundSessionKey = bindingRecord?.targetSessionKey?.trim(); + if (!bindingRecord || !boundSessionKey) { + return { bindingRecord: null, route: params.route }; + } + sessionBindingMocks.touch(bindingRecord.bindingId, undefined); + return { + bindingRecord, + boundSessionKey, + boundAgentId: params.route.agentId, + route: { + ...params.route, + sessionKey: boundSessionKey, + lastRoutePolicy: boundSessionKey === params.route.mainSessionKey ? "main" : "session", + matchedBy: "binding.channel", + }, + }; + }, + ensureConfiguredBindingRouteReady: persistentBindingMocks.ensureConfiguredBindingRouteReady, + readChannelAllowFromStore: conversationStoreMocks.readChannelAllowFromStore, + upsertChannelPairingRequest: conversationStoreMocks.upsertChannelPairingRequest, + getSessionBindingService: () => ({ + bind: vi.fn(), + getCapabilities: vi.fn(), + listBySession: vi.fn(), + resolveByConversation: (ref: unknown) => sessionBindingMocks.resolveByConversation(ref), + touch: (bindingId: string, at?: number) => sessionBindingMocks.touch(bindingId, at), + unbind: vi.fn(), + }), + }; +}); +vi.mock("openclaw/plugin-sdk/session-store-runtime", async () => { + const actual = await vi.importActual( + "openclaw/plugin-sdk/session-store-runtime", + ); + return { + ...actual, + getSessionEntry: sessionMocks.getSessionEntry, + sessionStoreEntries: sessionMocks.sessionStoreEntries, + resolveStorePath: sessionMocks.resolveStorePath, + updateSessionStoreEntry: sessionMocks.updateSessionStoreEntry, + }; +}); +vi.mock("openclaw/plugin-sdk/command-auth-native", async () => { + const actual = await vi.importActual( + "openclaw/plugin-sdk/command-auth-native", + ); + commandAuthMocks.resolveCommandArgMenu.mockImplementation(actual.resolveCommandArgMenu); + return { + ...actual, + resolveCommandArgMenu: commandAuthMocks.resolveCommandArgMenu, + }; +}); +vi.mock("openclaw/plugin-sdk/agent-runtime", async () => { + const actual = await vi.importActual( + "openclaw/plugin-sdk/agent-runtime", + ); + agentRuntimeMocks.resolveDefaultModelForAgent.mockImplementation( + actual.resolveDefaultModelForAgent, + ); + return { + ...actual, + loadPreparedModelCatalog: agentRuntimeMocks.loadModelCatalog, + resolveDefaultModelForAgent: agentRuntimeMocks.resolveDefaultModelForAgent, + }; +}); +vi.mock("./bot-native-commands.runtime.js", () => { + return { + ensureConfiguredBindingRouteReady: persistentBindingMocks.ensureConfiguredBindingRouteReady, + finalizeInboundContext: vi.fn((ctx: unknown) => ctx), + getAgentScopedMediaLocalRoots, + getSessionEntry: sessionMocks.getSessionEntry, + resolveChunkMode, + resolveThreadSessionKeys, + dispatchChannelInboundTurn: dispatchChannelInboundTurnMock as unknown as NonNullable< + TelegramNativeCommandDeps["dispatchChannelInboundTurn"] + >, + }; +}); +vi.mock("./bot/delivery.js", () => ({ + deliverReplies: deliveryMocks.deliverReplies, +})); +vi.mock("./bot/delivery.replies.js", () => ({ + deliverReplies: deliveryMocks.deliverReplies, +})); + +export let activePluginRegistry: ReturnType; + +type TelegramCommandHandler = (ctx: unknown) => Promise; +type TelegramPluginCommandSpecs = Array<{ + name: string; + description: string; + acceptsArgs?: boolean; +}>; +type TelegramLoginFlow = NonNullable; + +export function registerAndResolveStatusHandler(params: { + cfg: OpenClawConfig; + runtimeCfg?: OpenClawConfig; + allowFrom?: string[]; + groupAllowFrom?: string[]; + storeAllowFrom?: string[]; + telegramCfg?: NativeCommandTestParams["telegramCfg"]; + resolveTelegramGroupConfig?: RegisterTelegramHandlerParams["resolveTelegramGroupConfig"]; +}): { + handler: TelegramCommandHandler; + sendMessage: ReturnType; +} { + const { + cfg, + runtimeCfg, + allowFrom, + groupAllowFrom, + storeAllowFrom, + telegramCfg, + resolveTelegramGroupConfig, + } = params; + return registerAndResolveCommandHandlerBase({ + commandName: "status", + cfg, + runtimeCfg, + allowFrom: allowFrom ?? ["*"], + groupAllowFrom: groupAllowFrom ?? [], + storeAllowFrom, + telegramCfg, + resolveTelegramGroupConfig, + }); +} + +function registerAndResolveCommandHandlerBase(params: { + commandName: string; + cfg: OpenClawConfig; + runtimeCfg?: OpenClawConfig; + allowFrom: string[]; + groupAllowFrom: string[]; + storeAllowFrom?: string[]; + telegramCfg?: NativeCommandTestParams["telegramCfg"]; + resolveTelegramGroupConfig?: RegisterTelegramHandlerParams["resolveTelegramGroupConfig"]; + pluginCommandSpecs?: TelegramPluginCommandSpecs; + runModelsAuthLoginFlow?: TelegramLoginFlow; +}): { + handler: TelegramCommandHandler; + sendMessage: ReturnType; +} { + const { + commandName, + cfg, + runtimeCfg, + allowFrom, + groupAllowFrom, + storeAllowFrom, + telegramCfg, + resolveTelegramGroupConfig, + pluginCommandSpecs, + runModelsAuthLoginFlow, + } = params; + const commandHandlers = new Map(); + const sendMessage = vi.fn().mockResolvedValue(undefined); + const baseRuntimeCfg = runtimeCfg ?? cfg; + const commandRuntimeCfg = baseRuntimeCfg; + const telegramDeps: TelegramNativeCommandDeps = { + getRuntimeConfig: vi.fn(() => commandRuntimeCfg), + readChannelAllowFromStore: vi.fn(async () => storeAllowFrom ?? []), + dispatchChannelInboundTurn: dispatchChannelInboundTurnMock as unknown as NonNullable< + TelegramNativeCommandDeps["dispatchChannelInboundTurn"] + >, + listSkillCommandsForAgents: vi.fn(() => []), + syncTelegramMenuCommands: vi.fn(), + sendMessageTelegram: vi.fn(async (_to, text) => { + await sendMessage(100, text, {}); + return { messageId: "999", chatId: "100" }; + }), + ...(runModelsAuthLoginFlow ? { runModelsAuthLoginFlow } : {}), + }; + withPluginRuntimeRegistryScope(activePluginRegistry, () => { + for (const spec of pluginCommandSpecs ?? []) { + expect( + registerPluginCommand(`test-${spec.name}`, { + ...spec, + requireAuth: true, + handler: pluginRuntimeMocks.executePluginCommand, + }), + ).toEqual({ ok: true }); + } + registerTelegramNativeCommands({ + ...createNativeCommandTestParams({ + bot: { + api: { + setMyCommands: vi.fn().mockResolvedValue(undefined), + sendMessage, + }, + command: vi.fn((name: string, cb: TelegramCommandHandler) => { + commandHandlers.set(name, cb); + }), + } as unknown as NativeCommandTestParams["bot"], + cfg, + allowFrom, + groupAllowFrom, + telegramCfg, + resolveTelegramGroupConfig, + telegramDeps, + }), + }); + }); + + const handler = commandHandlers.get(commandName); + if (!handler) { + throw new Error(`expected ${commandName} command handler to be registered`); + } + return { handler, sendMessage }; +} + +export function registerAndResolveCommandHandler(params: { + commandName: string; + cfg: OpenClawConfig; + allowFrom?: string[]; + groupAllowFrom?: string[]; + storeAllowFrom?: string[]; + telegramCfg?: NativeCommandTestParams["telegramCfg"]; + resolveTelegramGroupConfig?: RegisterTelegramHandlerParams["resolveTelegramGroupConfig"]; + pluginCommandSpecs?: TelegramPluginCommandSpecs; + runModelsAuthLoginFlow?: TelegramLoginFlow; +}): { + handler: TelegramCommandHandler; + sendMessage: ReturnType; +} { + const { + commandName, + cfg, + allowFrom, + groupAllowFrom, + storeAllowFrom, + telegramCfg, + resolveTelegramGroupConfig, + pluginCommandSpecs, + runModelsAuthLoginFlow, + } = params; + return registerAndResolveCommandHandlerBase({ + commandName, + cfg, + allowFrom: allowFrom ?? [], + groupAllowFrom: groupAllowFrom ?? [], + storeAllowFrom, + telegramCfg, + resolveTelegramGroupConfig, + pluginCommandSpecs, + runModelsAuthLoginFlow, + }); +} + +export function requireValue(value: T | null | undefined, label: string): T { + if (value == null) { + throw new Error(`expected ${label}`); + } + return value; +} + +export const requireRecord = createRequireRecord("record", "expected-label-object"); + +export function firstMockArg( + mockFn: ReturnType, + label: string, + callIndex = 0, +): unknown { + const call = mockFn.mock.calls.at(callIndex); + if (!call) { + throw new Error(`expected ${label} call ${callIndex}`); + } + return call.at(0); +} + +export function expectRecordFields( + value: unknown, + expected: Record, + label: string, +): Record { + const record = requireRecord(value, label); + for (const [key, expectedValue] of Object.entries(expected)) { + expect(record[key], `${label}.${key}`).toEqual(expectedValue); + } + return record; +} + +export function expectSendMessageCall(params: { + sendMessage: ReturnType; + callIndex?: number; + chatId: unknown; + text?: string; + textIncludes?: string; + optionFields?: Record; + requireReplyMarkup?: boolean; + label: string; +}): Record { + const call = requireValue( + params.sendMessage.mock.calls[params.callIndex ?? 0], + `${params.label} sendMessage call`, + ); + expect(call[0]).toBe(params.chatId); + if (params.text !== undefined) { + expect(call[1]).toBe(params.text); + } + if (params.textIncludes !== undefined) { + expect(String(call[1])).toContain(params.textIncludes); + } + const options = params.optionFields + ? expectRecordFields(call[2], params.optionFields, `${params.label} sendMessage options`) + : requireRecord(call[2], `${params.label} sendMessage options`); + if (params.requireReplyMarkup) { + requireRecord(options.reply_markup, `${params.label} reply markup`); + } + return options; +} + +export function expectUnauthorizedNewCommandBlocked(sendMessage: ReturnType) { + expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); + expect(persistentBindingMocks.resolveConfiguredBindingRoute).not.toHaveBeenCalled(); + expect(persistentBindingMocks.ensureConfiguredBindingRouteReady).not.toHaveBeenCalled(); + expectSendMessageCall({ + sendMessage, + chatId: -1001234567890, + text: "You are not authorized to use this command.", + optionFields: { message_thread_id: 42 }, + label: "unauthorized /new", + }); +} + +export function resetSessionMetaMocks() { + persistentBindingMocks.resolveConfiguredBindingRoute.mockClear(); + persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => + createConfiguredBindingRoute(route, null), + ); + persistentBindingMocks.ensureConfiguredBindingRouteReady.mockClear(); + persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ ok: true }); + commandAuthMocks.resolveCommandArgMenu.mockClear().mockImplementation(({ command, args }) => { + if (args?.raw || (args?.values && Object.keys(args.values).length > 0)) { + return null; + } + const arg = command.args?.[0]; + if (!arg) { + return null; + } + if (command.key === "think") { + return { + arg, + choices: ["low", "medium", "high"].map((value) => ({ label: value, value })), + }; + } + if (command.key === "fast") { + const choices = ["on", "off", "auto (30 sec)", "default", "status"]; + return { + arg, + choices: choices.map((value) => ({ label: value, value })), + }; + } + return null; + }); + agentRuntimeMocks.loadModelCatalog.mockClear().mockResolvedValue([ + { + provider: "openai", + id: "gpt-5.5", + name: "GPT-5.5", + reasoning: true, + }, + ]); + sessionMocks.getSessionEntry.mockClear().mockReturnValue(undefined); + sessionMocks.sessionStoreEntries.mockClear().mockReturnValue({}); + sessionMocks.getSessionEntry.mockImplementation( + ({ storePath, sessionKey }: { storePath: string; sessionKey: string }) => + sessionMocks.sessionStoreEntries(storePath)[sessionKey], + ); + sessionMocks.updateSessionStoreEntry.mockClear().mockImplementation(async (params) => { + const current = sessionMocks.sessionStoreEntries(params.storePath)[params.sessionKey]; + if (!current) { + return null; + } + const patch = await params.update({ ...current }); + return patch ? { ...current, ...patch } : current; + }); + sessionMocks.recordSessionMetaFromInbound.mockClear().mockResolvedValue(undefined); + sessionMocks.resolveStorePath.mockClear().mockReturnValue("/tmp/openclaw-sessions.json"); + pluginRuntimeMocks.executePluginCommand.mockClear().mockResolvedValue({ text: "ok" }); + activePluginRegistry = createEmptyPluginRegistry(); + replyMocks.dispatchReplyWithBufferedBlockDispatcher + .mockClear() + .mockResolvedValue(dispatchReplyResult); + dispatchChannelInboundTurnMock.mockClear(); + sessionBindingMocks.resolveByConversation.mockReset().mockReturnValue(null); + sessionBindingMocks.touch.mockReset(); + deliveryMocks.deliverReplies.mockClear().mockResolvedValue({ delivered: true }); +} + +activePluginRegistry = createEmptyPluginRegistry(); +const { registerTelegramNativeCommands } = await import("./bot-native-commands.js"); +resetSessionMetaMocks(); +const warmStatusHandler = registerAndResolveStatusHandler({ cfg: {} }); +await warmStatusHandler.handler(createTelegramPrivateCommandContext()); diff --git a/extensions/telegram/src/bot-native-commands.login.test.ts b/extensions/telegram/src/bot-native-command-login.test.ts similarity index 57% rename from extensions/telegram/src/bot-native-commands.login.test.ts rename to extensions/telegram/src/bot-native-command-login.test.ts index a1ae41c28a1c..d7b7f06bf941 100644 --- a/extensions/telegram/src/bot-native-commands.login.test.ts +++ b/extensions/telegram/src/bot-native-command-login.test.ts @@ -7,7 +7,9 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; import { createDeferred } from "openclaw/plugin-sdk/extension-shared"; import type { ModelsAuthLoginFlowOptions } from "openclaw/plugin-sdk/provider-auth-login-flow-runtime"; import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env"; +import type { SessionEntry } from "openclaw/plugin-sdk/session-store-runtime"; import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { TelegramNativeCommandDeps } from "./bot-native-command-deps.runtime.js"; import { createTelegramGroupCommandContext } from "./bot-native-commands.fixture-test-support.js"; import { registerTelegramNativeCommands } from "./bot-native-commands.js"; import { @@ -19,12 +21,18 @@ import { import { telegramBotInfoForTest } from "./bot.create-telegram-bot.test-support.js"; import { resetTelegramForumFlagCacheForTest } from "./bot/helpers.js"; +const loginSessionMocks = vi.hoisted(() => ({ + getSessionEntry: vi.fn(), + loadSessionStore: vi.fn(), + resolveStorePath: vi.fn(), + updateSessionStoreEntry: vi.fn(), +})); + vi.mock("./bot-native-commands.runtime.js", () => ({ ensureConfiguredBindingRouteReady: vi.fn(async () => ({ ok: true })), finalizeInboundContext: vi.fn((ctx: unknown) => ctx), getAgentScopedMediaLocalRoots: vi.fn(() => []), - getSessionEntry: vi.fn(() => undefined), - recordInboundSessionMetaSafe: vi.fn(async () => undefined), + getSessionEntry: loginSessionMocks.getSessionEntry, resolveChunkMode: vi.fn(() => "length"), resolveThreadSessionKeys: vi.fn( ({ @@ -39,26 +47,33 @@ vi.mock("./bot-native-commands.runtime.js", () => ({ }), ), })); -vi.mock("openclaw/plugin-sdk/session-store-runtime", () => ({ - formatSqliteSessionFileMarker: vi.fn(() => "sqlite:test"), - getSessionEntry: vi.fn(() => undefined), - resolveStorePath: vi.fn(() => "/tmp/openclaw-login-test.sqlite"), - updateSessionStoreEntry: vi.fn(async () => undefined), -})); +vi.mock("openclaw/plugin-sdk/session-store-runtime", async () => { + const actual = await vi.importActual( + "openclaw/plugin-sdk/session-store-runtime", + ); + return { + ...actual, + getSessionEntry: loginSessionMocks.getSessionEntry, + resolveStorePath: loginSessionMocks.resolveStorePath, + updateSessionStoreEntry: loginSessionMocks.updateSessionStoreEntry, + }; +}); type LoginFlowMock = ReturnType; +type TelegramLoginFlow = NonNullable; let loginAccountIndex = 0; function registerLoginCommand(params: { cfg: OpenClawConfig; loginFlow: LoginFlowMock; + accountId?: string; allowFrom?: string[]; abortSignal?: AbortSignal; runtime?: RuntimeEnv; }) { const botHarness = createCommandBot(); - const accountId = `login-test-${++loginAccountIndex}`; + const accountId = params.accountId ?? `login-test-${++loginAccountIndex}`; const nativeParams = createNativeCommandTestParams(params.cfg, { accountId, bot: botHarness.bot, @@ -106,6 +121,22 @@ describe("registerTelegramNativeCommands /login", () => { beforeEach(() => { resetTelegramForumFlagCacheForTest(); resetNativeCommandMenuMocks(); + loginSessionMocks.loadSessionStore.mockReset().mockReturnValue({}); + loginSessionMocks.getSessionEntry + .mockReset() + .mockImplementation( + ({ storePath, sessionKey }: { storePath: string; sessionKey: string }) => + loginSessionMocks.loadSessionStore(storePath)[sessionKey], + ); + loginSessionMocks.resolveStorePath.mockReset().mockReturnValue("/tmp/openclaw-sessions.json"); + loginSessionMocks.updateSessionStoreEntry.mockReset().mockImplementation(async (params) => { + const current = loginSessionMocks.loadSessionStore(params.storePath)[params.sessionKey]; + if (!current) { + return null; + } + const patch = await params.update({ ...current }); + return patch ? { ...current, ...patch } : current; + }); }); it("handles /login codex by sending the device code before login completes", async () => { @@ -532,4 +563,366 @@ describe("registerTelegramNativeCommands /login", () => { ); expect(sendMessage).toHaveBeenCalledTimes(1); }); + it("moves the target session to the profile returned by Telegram /login codex", async () => { + const finishLogin = createDeferred(); + loginSessionMocks.loadSessionStore.mockReturnValue({ + "agent:main:main": { + authProfileOverride: "openai:owner@example.com", + sessionId: "sess-main", + updatedAt: 1, + }, + }); + const runModelsAuthLoginFlow = vi.fn(async (opts) => { + await opts.prompter.deviceCode?.({ + title: "OpenAI Codex device code", + code: "ABCD-EFGH", + expiresInMinutes: 15, + message: "URL: https://auth.openai.com/codex/device", + }); + await finishLogin.promise; + return { + providerId: "openai", + methodId: "device-code", + profiles: [ + { profileId: "openai:new-owner@example.com", provider: "openai", mode: "oauth" }, + ], + }; + }); + + const { handler, sendMessage } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + expect(loginSessionMocks.updateSessionStoreEntry).not.toHaveBeenCalled(); + finishLogin.resolve(); + + expect(runModelsAuthLoginFlow).toHaveBeenCalledWith( + expect.objectContaining({ + provider: "openai", + method: "device-code", + agent: "main", + }), + ); + expect( + (runModelsAuthLoginFlow.mock.calls[0]?.[0] as { profileId?: string } | undefined)?.profileId, + ).toBeUndefined(); + await vi.waitFor(() => + expect(loginSessionMocks.updateSessionStoreEntry).toHaveBeenCalledWith({ + sessionKey: "agent:main:main", + storePath: "/tmp/openclaw-sessions.json", + requireWriteSuccess: true, + skipMaintenance: true, + update: expect.any(Function), + }), + ); + const patchUpdate = ( + loginSessionMocks.updateSessionStoreEntry.mock.calls[0]?.[0] as { + update?: (entry: Record) => Record; + } + )?.update?.({ + authProfileOverride: "openai:owner@example.com", + sessionId: "sess-main", + updatedAt: 1, + }); + expect(patchUpdate).toEqual({ + authProfileOverride: "openai:new-owner@example.com", + authProfileOverrideSource: "user", + authProfileOverrideCompactionCount: undefined, + }); + await vi.waitFor(() => + expect(sendMessage).toHaveBeenCalledWith( + 100, + "Codex login complete. Try your request again now.", + {}, + ), + ); + }); + + it("moves a session created while Telegram login is pending to the returned profile", async () => { + const finishLogin = createDeferred(); + let sessionStore: Record = {}; + loginSessionMocks.loadSessionStore.mockImplementation(() => sessionStore); + const runModelsAuthLoginFlow = vi.fn(async (opts) => { + await opts.prompter.deviceCode?.({ + title: "OpenAI Codex device code", + code: "NEW-SESSION", + }); + await finishLogin.promise; + return { + providerId: "openai", + methodId: "device-code", + profiles: [ + { profileId: "openai:new-owner@example.com", provider: "openai", mode: "oauth" }, + ], + }; + }); + const { handler, sendMessage } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + sessionStore = { + "agent:main:main": { + sessionId: "sess-created-during-login", + updatedAt: 2, + }, + }; + finishLogin.resolve(); + + await vi.waitFor(() => + expect(loginSessionMocks.updateSessionStoreEntry).toHaveBeenCalledTimes(1), + ); + const update = ( + loginSessionMocks.updateSessionStoreEntry.mock.calls[0]?.[0] as { + update?: (entry: SessionEntry) => Partial | null; + } + )?.update; + expect( + update?.({ + sessionId: "sess-created-during-login", + updatedAt: 2, + }), + ).toEqual({ + authProfileOverride: "openai:new-owner@example.com", + authProfileOverrideSource: "user", + authProfileOverrideCompactionCount: undefined, + }); + await vi.waitFor(() => + expect(sendMessage).toHaveBeenCalledWith( + 100, + "Codex login complete. Try your request again now.", + {}, + ), + ); + }); + + it("preserves a later user-selected profile on a session created during Telegram login", async () => { + const finishLogin = createDeferred(); + let sessionStore: Record = {}; + loginSessionMocks.loadSessionStore.mockImplementation(() => sessionStore); + const runModelsAuthLoginFlow = vi.fn(async (opts) => { + await opts.prompter.deviceCode?.({ + title: "OpenAI Codex device code", + code: "LATER-USER-SELECTION", + }); + await finishLogin.promise; + return { + providerId: "openai", + methodId: "device-code", + profiles: [{ profileId: "openai:login-profile", provider: "openai", mode: "oauth" }], + }; + }); + const { handler, sendMessage } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + sessionStore = { + "agent:main:main": { + authProfileOverride: "openai:later-user-profile", + authProfileOverrideSource: "user", + sessionId: "sess-created-during-login", + updatedAt: 2, + }, + }; + finishLogin.resolve(); + + await vi.waitFor(() => + expect(sendMessage).toHaveBeenCalledWith( + 100, + "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", + {}, + ), + ); + expect(sessionStore["agent:main:main"]?.authProfileOverride).toBe("openai:later-user-profile"); + expect(sendMessage).not.toHaveBeenCalledWith( + 100, + "Codex login complete. Try your request again now.", + expect.any(Object), + ); + }); + + it("marks a same-profile Telegram login as user-selected", async () => { + loginSessionMocks.loadSessionStore.mockReturnValue({ + "agent:main:main": { + authProfileOverride: "openai:owner@example.com", + authProfileOverrideSource: "auto", + authProfileOverrideCompactionCount: 2, + sessionId: "sess-main", + updatedAt: 1, + }, + }); + const runModelsAuthLoginFlow = vi.fn(async () => ({ + providerId: "openai", + methodId: "device-code", + profiles: [{ profileId: "openai:owner@example.com", provider: "openai", mode: "oauth" }], + })); + const { handler } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + + const update = ( + loginSessionMocks.updateSessionStoreEntry.mock.calls[0]?.[0] as { + update?: (entry: Record) => Record; + } + )?.update; + expect(update).toBeTypeOf("function"); + expect( + update?.({ + authProfileOverride: "openai:owner@example.com", + authProfileOverrideSource: "auto", + authProfileOverrideCompactionCount: 2, + sessionId: "sess-main", + updatedAt: 1, + }), + ).toEqual({ + authProfileOverride: "openai:owner@example.com", + authProfileOverrideSource: "user", + authProfileOverrideCompactionCount: undefined, + }); + expect( + update?.({ + authProfileOverride: "openai:owner@example.com", + authProfileOverrideSource: "user", + sessionId: "sess-main", + updatedAt: 2, + }), + ).toBeNull(); + }); + + it("reports partial success when Telegram cannot persist the returned profile", async () => { + loginSessionMocks.loadSessionStore.mockReturnValue({ + "agent:main:main": { + authProfileOverride: "openai:old-owner@example.com", + sessionId: "sess-main", + updatedAt: 1, + }, + }); + loginSessionMocks.updateSessionStoreEntry.mockRejectedValueOnce(new Error("write failed")); + const runModelsAuthLoginFlow = vi.fn(async () => ({ + providerId: "openai", + methodId: "device-code", + profiles: [{ profileId: "openai:new-owner@example.com", provider: "openai", mode: "oauth" }], + })); + const { handler, sendMessage } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + + expect(sendMessage).toHaveBeenCalledWith( + 100, + "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", + {}, + ); + expect(sendMessage).not.toHaveBeenCalledWith( + 100, + "Codex login complete. Try your request again now.", + expect.any(Object), + ); + }); + + it("reports partial success when Telegram login returns no OpenAI profile", async () => { + const runModelsAuthLoginFlow = vi.fn(async () => ({ + providerId: "openai", + methodId: "device-code", + profiles: [], + })); + const { handler, sendMessage } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + + expect(sendMessage).toHaveBeenCalledWith( + 100, + "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", + {}, + ); + expect(sendMessage).not.toHaveBeenCalledWith( + 100, + "Codex login complete. Try your request again now.", + expect.any(Object), + ); + }); + + it("revalidates an unchanged Telegram profile after device login", async () => { + const previousEntry = { + authProfileOverride: "openai:owner@example.com", + authProfileOverrideSource: "user", + sessionId: "sess-main", + updatedAt: 1, + }; + loginSessionMocks.loadSessionStore.mockReturnValue({ + "agent:main:main": previousEntry, + }); + loginSessionMocks.updateSessionStoreEntry.mockImplementationOnce(async (params) => { + const concurrentEntry = { + ...previousEntry, + authProfileOverride: "openai:concurrent-owner@example.com", + updatedAt: 2, + }; + const patch = await params.update({ ...concurrentEntry }); + return patch ? { ...concurrentEntry, ...patch } : concurrentEntry; + }); + const runModelsAuthLoginFlow = vi.fn(async () => ({ + providerId: "openai", + methodId: "device-code", + profiles: [{ profileId: "openai:owner@example.com", provider: "openai", mode: "oauth" }], + })); + const { handler, sendMessage } = registerLoginCommand({ + accountId: "default", + cfg: { + commands: { native: true, ownerAllowFrom: ["200"] }, + } as OpenClawConfig, + allowFrom: ["200"], + loginFlow: runModelsAuthLoginFlow, + }); + + await handler(createPrivateCommandContext({ match: "codex", userId: 200 })); + + expect(sendMessage).toHaveBeenCalledWith( + 100, + "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", + {}, + ); + expect(sendMessage).not.toHaveBeenCalledWith( + 100, + "Codex login complete. Try your request again now.", + expect.any(Object), + ); + }); }); diff --git a/extensions/telegram/src/bot-native-command-login.ts b/extensions/telegram/src/bot-native-command-login.ts new file mode 100644 index 000000000000..69c17747f45d --- /dev/null +++ b/extensions/telegram/src/bot-native-command-login.ts @@ -0,0 +1,271 @@ +// Telegram plugin module implements native Codex login behavior. +import type { CommandArgs } from "openclaw/plugin-sdk/command-auth-native"; +import { createDeferred } from "openclaw/plugin-sdk/extension-shared"; +import { codexChannelLoginRuntime } from "openclaw/plugin-sdk/provider-auth-login-flow-runtime"; +import { danger } from "openclaw/plugin-sdk/runtime-env"; +import { + resolveStorePath, + updateSessionStoreEntry, +} from "openclaw/plugin-sdk/session-store-runtime"; +import { escapeHtml } from "openclaw/plugin-sdk/text-utility-runtime"; +import { withTelegramApiErrorLogging } from "./api-logging.js"; +import { defaultTelegramNativeCommandDeps } from "./bot-native-command-deps.runtime.js"; +import type { TelegramCommandDispatch } from "./bot-native-command-dispatch.js"; +import { buildTelegramRoutingTarget } from "./bot/helpers.js"; + +const activeTelegramCodexLoginFlows = codexChannelLoginRuntime.createFlowRegistry(); + +type TelegramLoginDeviceCode = { + title: string; + code: string; + expiresInMinutes?: number; + message?: string; +}; + +// Telegram's inline-code entity provides the tap-to-copy affordance needed for +// short-lived device codes; plain text and literal backticks do not. +function formatTelegramLoginDeviceCode(params: TelegramLoginDeviceCode): string { + return [ + `${escapeHtml(params.title)}`, + "", + ...(params.message ? [escapeHtml(params.message)] : []), + `Code: ${escapeHtml(params.code)}`, + ...(params.expiresInMinutes + ? [`Code expires in ${params.expiresInMinutes} minutes. Never share it.`] + : []), + ].join("\n"); +} + +function resolveTelegramCodexLoginProviderInput(commandArgs: CommandArgs | undefined): string { + const providerValue = commandArgs?.values?.provider; + return typeof providerValue === "string" && providerValue.trim() + ? providerValue + : (commandArgs?.raw ?? "codex"); +} + +function buildTelegramCodexLoginFlowKey(params: { + dispatch: TelegramCommandDispatch; + provider: string; +}): string { + const { dispatch } = params; + const threadKey = + dispatch.threadSpec.id == null + ? dispatch.threadSpec.scope + : `${dispatch.threadSpec.scope}:${dispatch.threadSpec.id}`; + return [ + "telegram", + dispatch.route.accountId, + String(dispatch.chatId), + threadKey, + dispatch.route.agentId, + params.provider, + ].join(":"); +} + +export async function executeTelegramLoginCommand(params: { + dispatch: TelegramCommandDispatch; + commandArgs?: CommandArgs; +}): Promise { + const { dispatch } = params; + const sendLoginMessage = async (text: string) => { + await withTelegramApiErrorLogging({ + operation: "sendMessage", + runtime: dispatch.runtime, + fn: () => dispatch.bot.api.sendMessage(dispatch.chatId, text, dispatch.threadParams ?? {}), + }); + }; + const sendLoginDeviceCode = async (deviceCode: TelegramLoginDeviceCode) => { + await withTelegramApiErrorLogging({ + operation: "sendMessage", + runtime: dispatch.runtime, + fn: () => + dispatch.bot.api.sendMessage(dispatch.chatId, formatTelegramLoginDeviceCode(deviceCode), { + ...dispatch.threadParams, + parse_mode: "HTML", + }), + }); + }; + const sendLoginResultMessage = async (text: string) => { + await dispatch.telegramDeps.sendMessageTelegram( + buildTelegramRoutingTarget(dispatch.chatId, dispatch.threadSpec), + text, + { + cfg: dispatch.runtimeCfg, + token: dispatch.opts.token, + accountId: dispatch.route.accountId, + }, + ); + }; + if ( + !dispatch.senderIsOwner || + !codexChannelLoginRuntime.hasConfiguredCommandOwnerAllowlist(dispatch.runtimeCfg) + ) { + await sendLoginMessage("Only a configured OpenClaw owner can start Codex login from Telegram."); + return false; + } + if (dispatch.isGroup) { + await sendLoginMessage( + "For safety, Codex login codes are only sent in a private chat with this bot. DM this bot `/login codex` to pair Codex.", + ); + return true; + } + const loginProvider = codexChannelLoginRuntime.resolveProvider( + resolveTelegramCodexLoginProviderInput(params.commandArgs), + ); + if (!loginProvider) { + await sendLoginMessage("Unsupported login provider. Use `/login codex`."); + return false; + } + const flowKey = buildTelegramCodexLoginFlowKey({ dispatch, provider: loginProvider }); + const reservation = codexChannelLoginRuntime.reserveFlow({ + flows: activeTelegramCodexLoginFlows, + flowKey, + }); + if (reservation.status === "active") { + await sendLoginMessage( + "A Codex login code is already active for this Telegram chat. Complete it, or wait for it to expire before requesting a new one.", + ); + return true; + } + const flowSignal = dispatch.opts.accountAbortSignal + ? AbortSignal.any([reservation.record.signal, dispatch.opts.accountAbortSignal]) + : reservation.record.signal; + const deviceCodeDelivered = createDeferred(); + let deviceCodeWasDelivered = false; + // Device-code delivery releases Telegram's serialized chat lane. The + // reservation and account signal still own polling through completion. + const completion = (async () => { + const sessionSwitchFailedMessage = + "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually."; + let terminalMessage: string; + const loginFlow = + dispatch.telegramDeps.runModelsAuthLoginFlow ?? + defaultTelegramNativeCommandDeps.runModelsAuthLoginFlow; + try { + if (!loginFlow) { + throw new Error("Codex login flow is unavailable."); + } + const targetSessionEntryAtStart = dispatch.nativeCommandRuntime.getSessionEntry({ + agentId: dispatch.route.agentId, + sessionKey: dispatch.targetSessionKey, + }); + const loginResult = await codexChannelLoginRuntime.runDeviceLoginFlow({ + runLoginFlow: loginFlow, + provider: loginProvider, + agentId: dispatch.route.agentId, + config: dispatch.runtimeCfg, + runtime: dispatch.runtime, + signal: flowSignal, + sendMessage: sendLoginMessage, + sendDeviceCode: async (deviceCode) => { + flowSignal.throwIfAborted(); + await sendLoginDeviceCode(deviceCode); + flowSignal.throwIfAborted(); + deviceCodeWasDelivered = true; + deviceCodeDelivered.resolve(); + }, + unsupportedPromptMessage: "Telegram /login supports only fixed Codex device-code auth.", + }); + flowSignal.throwIfAborted(); + const nextProfileId = loginResult.profiles.find( + (profile) => profile.provider === loginProvider, + )?.profileId; + terminalMessage = "Codex login complete. Try your request again now."; + if (!nextProfileId) { + terminalMessage = sessionSwitchFailedMessage; + } else { + const storePath = resolveStorePath(dispatch.runtimeCfg.session?.store, { + agentId: dispatch.route.agentId, + }); + let entryObserved = false; + let adoptionAllowed = false; + try { + const persisted = await updateSessionStoreEntry({ + sessionKey: dispatch.targetSessionKey, + storePath, + requireWriteSuccess: true, + skipMaintenance: true, + update: (entry) => { + entryObserved = true; + const source = + entry.authProfileOverrideSource ?? + (typeof entry.authProfileOverrideCompactionCount === "number" + ? "auto" + : entry.authProfileOverride + ? "user" + : undefined); + if ( + flowSignal.aborted || + (targetSessionEntryAtStart + ? entry.sessionId !== targetSessionEntryAtStart.sessionId || + entry.authProfileOverride !== targetSessionEntryAtStart.authProfileOverride || + entry.authProfileOverrideSource !== + targetSessionEntryAtStart.authProfileOverrideSource || + entry.authProfileOverrideCompactionCount !== + targetSessionEntryAtStart.authProfileOverrideCompactionCount + : source === "user" && entry.authProfileOverride !== nextProfileId) + ) { + return null; + } + adoptionAllowed = true; + return entry.authProfileOverride !== nextProfileId || + entry.authProfileOverrideSource !== "user" || + entry.authProfileOverrideCompactionCount !== undefined + ? { + authProfileOverride: nextProfileId, + authProfileOverrideSource: "user", + authProfileOverrideCompactionCount: undefined, + } + : null; + }, + }); + flowSignal.throwIfAborted(); + if ( + entryObserved && + (!adoptionAllowed || + !persisted || + persisted.authProfileOverride !== nextProfileId || + persisted.authProfileOverrideSource !== "user" || + persisted.authProfileOverrideCompactionCount !== undefined) + ) { + terminalMessage = sessionSwitchFailedMessage; + } + } catch (error) { + flowSignal.throwIfAborted(); + dispatch.runtime.error?.( + danger( + `telegram /login codex completed but failed to update session auth profile: ${String( + error, + )}`, + ), + ); + terminalMessage = sessionSwitchFailedMessage; + } + } + } catch (error) { + if (flowSignal.aborted) { + return; + } + dispatch.runtime.error?.(danger(`telegram /login codex failed: ${String(error)}`)); + terminalMessage = "Codex login did not complete. Send `/login codex` to request a new code."; + } + if (flowSignal.aborted) { + return; + } + try { + await sendLoginResultMessage(terminalMessage); + } catch (error) { + dispatch.runtime.error?.( + danger(`telegram /login codex result notification failed: ${String(error)}`), + ); + } + })().finally(() => { + codexChannelLoginRuntime.releaseFlow({ + flows: activeTelegramCodexLoginFlows, + flowKey, + record: reservation.record, + }); + }); + await Promise.race([deviceCodeDelivered.promise, completion]); + return deviceCodeWasDelivered; +} diff --git a/extensions/telegram/src/bot-native-command-plugins.test.ts b/extensions/telegram/src/bot-native-command-plugins.test.ts new file mode 100644 index 000000000000..acf7a1cb2b76 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-plugins.test.ts @@ -0,0 +1,692 @@ +import { + createEmptyPluginRegistry, + resetPluginRuntimeStateForTest, + setActivePluginRegistry, +} from "openclaw/plugin-sdk/channel-test-helpers"; +// Telegram tests cover bot native commands plugin behavior. +import type { OpenClawConfig, TelegramAccountConfig } from "openclaw/plugin-sdk/config-contracts"; +import { clearPluginCommands, registerPluginCommand } from "openclaw/plugin-sdk/plugin-runtime"; +import type { SessionEntry } from "openclaw/plugin-sdk/session-store-runtime"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { createTelegramTopicCommandContext } from "./bot-native-commands.fixture-test-support.js"; +import { + createCommandBot, + createNativeCommandTestParams, + createPrivateCommandContext, + deliverReplies, + editMessageTelegram, + emitTelegramMessageSentHooks, + resetNativeCommandMenuMocks, +} from "./bot-native-commands.menu-test-support.js"; +import { resetTelegramForumFlagCacheForTest } from "./bot/helpers.js"; + +const pluginSessionMocks = vi.hoisted(() => ({ + getSessionEntry: vi.fn(), + resolveStorePath: vi.fn(), +})); + +vi.mock("openclaw/plugin-sdk/session-store-runtime", async () => { + const actual = await vi.importActual( + "openclaw/plugin-sdk/session-store-runtime", + ); + return { + ...actual, + getSessionEntry: pluginSessionMocks.getSessionEntry, + resolveStorePath: pluginSessionMocks.resolveStorePath, + }; +}); +type CommandBotHarness = ReturnType; +type PlugCommandHarnessParams = { + botHarness?: CommandBotHarness; + cfg?: OpenClawConfig; + command?: Record; + acceptsArgs?: boolean; + args?: string; + result?: Record; + registerOverrides?: Partial[0]>; +}; + +const pluginCommandHandler = vi.fn(async (_ctx: Record) => ({ text: "ok" })); + +function registerTestPluginCommand(params: { + name: string; + description: string; + acceptsArgs?: boolean; + command?: Record; + result?: Record; +}) { + expect( + registerPluginCommand(`test-${params.name}`, { + name: params.name, + description: params.description, + acceptsArgs: params.acceptsArgs, + requireAuth: false, + ...params.command, + handler: async (ctx) => { + const handlerResult = await pluginCommandHandler(ctx as unknown as Record); + return params.result ?? handlerResult; + }, + }), + ).toEqual({ ok: true }); +} + +function primePlugCommand(params: PlugCommandHarnessParams = {}) { + registerTestPluginCommand({ + name: "plug", + description: "Plugin command", + acceptsArgs: params.acceptsArgs ?? true, + command: params.command, + result: params.result, + }); +} + +function registerPlugCommand(params: PlugCommandHarnessParams = {}) { + const botHarness = params.botHarness ?? createCommandBot(); + primePlugCommand(params); + registerTelegramNativeCommands({ + ...createNativeCommandTestParams(params.cfg ?? {}, { + bot: botHarness.bot, + }), + ...params.registerOverrides, + }); + const handler = botHarness.commandHandlers.get("plug"); + if (!handler) { + throw new Error("expected plug command handler to be registered"); + } + return { + ...botHarness, + handler, + }; +} + +function firstCall(mock: { mock: { calls: Array> } }) { + const call = mock.mock.calls.at(0); + if (!call) { + throw new Error("expected first mock call"); + } + return call; +} + +function firstCallArg(mock: { mock: { calls: Array> } }, argIndex = 0) { + const arg = firstCall(mock)[argIndex]; + if (!arg || typeof arg !== "object") { + throw new Error(`expected first mock call arg ${argIndex}`); + } + return arg as Record; +} + +function firstDeliverRepliesParams() { + return firstCallArg(deliverReplies as unknown as { mock: { calls: Array> } }); +} + +function firstExecutePluginCommandParams() { + return firstCallArg( + pluginCommandHandler as unknown as { + mock: { calls: Array> }; + }, + ); +} + +function replyAt(params: Record, index = 0) { + const replies = params.replies as Array> | undefined; + const reply = replies?.[index]; + if (!reply) { + throw new Error(`expected reply ${index}`); + } + return reply; +} + +resetPluginRuntimeStateForTest(); +setActivePluginRegistry(createEmptyPluginRegistry()); +const { registerTelegramNativeCommands } = await import("./bot-native-commands.js"); +registerTelegramNativeCommands(createNativeCommandTestParams({})); + +describe("registerTelegramNativeCommands", () => { + beforeEach(() => { + resetTelegramForumFlagCacheForTest(); + resetNativeCommandMenuMocks(); + resetPluginRuntimeStateForTest(); + setActivePluginRegistry(createEmptyPluginRegistry()); + clearPluginCommands(); + pluginCommandHandler.mockReset().mockResolvedValue({ text: "ok" }); + pluginSessionMocks.getSessionEntry.mockReset().mockReturnValue(undefined); + pluginSessionMocks.resolveStorePath.mockReset().mockReturnValue("/tmp/openclaw-sessions.json"); + }); + + it("passes agent-scoped media roots for plugin command replies with media", async () => { + const mediaMaxBytes = 50 * 1024 * 1024; + const cfg: OpenClawConfig = { + agents: { + list: [{ id: "main", default: true }, { id: "work" }], + }, + bindings: [{ agentId: "work", match: { channel: "telegram", accountId: "default" } }], + }; + + const { handler, sendMessage } = registerPlugCommand({ + cfg, + result: { + text: "with media", + mediaUrl: "/tmp/workspace-work/render.png", + }, + registerOverrides: { + mediaMaxBytes, + } as Partial[0]>, + }); + + await handler(createPrivateCommandContext()); + + const deliverParams = firstDeliverRepliesParams(); + expect(deliverParams.mediaMaxBytes).toBe(mediaMaxBytes); + const mediaLocalRoots = deliverParams.mediaLocalRoots as Array | undefined; + expect(mediaLocalRoots?.some((root) => /[\\/]\.openclaw[\\/]workspace-work$/.test(root))).toBe( + true, + ); + expect(sendMessage).not.toHaveBeenCalledWith(123, "Command not found."); + }); + + it("delivers presentation-only tables returned by plugin commands", async () => { + const presentation = { + title: "FY25 outlook", + blocks: [ + { + type: "table", + caption: "Pipeline", + headers: ["Account", "Stage"], + rows: [["Acme", "Won"]], + }, + ], + }; + const { handler } = registerPlugCommand({ result: { presentation } }); + + await handler(createPrivateCommandContext()); + + expect(replyAt(firstDeliverRepliesParams())).toMatchObject({ presentation }); + expect(replyAt(firstDeliverRepliesParams()).text).toBeUndefined(); + }); + + it("delivers Telegram button-only plugin command replies", async () => { + const buttons = [[{ text: "Retry", callback_data: "retry" }]]; + const { handler } = registerPlugCommand({ + result: { channelData: { telegram: { buttons } } }, + }); + + await handler(createPrivateCommandContext()); + + expect(replyAt(firstDeliverRepliesParams())).toEqual({ + channelData: { telegram: { buttons } }, + }); + }); + + it("targets reaction-only plugin replies at the invoking command message", async () => { + const { handler } = registerPlugCommand({ + result: { channelData: { telegram: { reaction: { emoji: "🔥" } } } }, + }); + + await handler(createPrivateCommandContext({ messageId: 321 })); + + const deliveryParams = firstDeliverRepliesParams(); + expect(replyAt(deliveryParams)).toEqual({ + replyToId: "321", + channelData: { telegram: { reaction: { emoji: "🔥" } } }, + }); + expect(deliveryParams.replyToMode).toBe("all"); + }); + + it("uses the empty-response fallback for unrelated metadata-only plugin results", async () => { + const { handler } = registerPlugCommand({ + result: { channelData: { plugin: { traceId: "trace-1" } } }, + }); + + await handler(createPrivateCommandContext()); + + expect(replyAt(firstDeliverRepliesParams())).toEqual({ + text: "No response generated. Please try again.", + }); + }); + + it("replies to unmatched plugin commands in the originating forum topic", async () => { + const { handler, sendMessage } = registerPlugCommand({ acceptsArgs: false }); + + await handler({ + match: "unexpected", + message: { + message_id: 2, + date: Math.floor(Date.now() / 1000), + chat: { + id: -1001234567890, + type: "supergroup", + title: "Forum Group", + is_forum: true, + }, + message_thread_id: 77, + from: { id: 200, username: "bob" }, + }, + }); + + const sendMessageCall = firstCall(sendMessage); + expect(sendMessageCall[0]).toBe(-1001234567890); + expect(sendMessageCall[1]).toBe("Command not found."); + expect( + (sendMessageCall[2] as { message_thread_id?: number } | undefined)?.message_thread_id, + ).toBe(77); + }); + + it("uses plugin command metadata to send and edit a Telegram progress placeholder", async () => { + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { + telegram: + "Running this command now...\n\nI'll edit this message with the final result when it's ready.", + }, + }, + result: { + text: "Command completed successfully", + }, + }); + + await handler( + createPrivateCommandContext({ + match: "now", + }), + ); + + const sendMessageCall = firstCall(sendMessage); + expect(sendMessageCall[0]).toBe(100); + expect(String(sendMessageCall[1])).toContain("Running this command now"); + expect(sendMessageCall[2]).toBeUndefined(); + const editCall = firstCall( + editMessageTelegram as unknown as { mock: { calls: Array> } }, + ); + expect(editCall[0]).toBe(100); + expect(editCall[1]).toBe(999); + expect(String(editCall[2])).toContain("Command completed successfully"); + expect((editCall[3] as { accountId?: string } | undefined)?.accountId).toBe("default"); + expect(deleteMessage).not.toHaveBeenCalled(); + expect(deliverReplies).not.toHaveBeenCalled(); + const hookParams = firstCallArg( + emitTelegramMessageSentHooks as unknown as { mock: { calls: Array> } }, + ); + expect(hookParams.chatId).toBe("100"); + expect(hookParams.content).toBe("Command completed successfully"); + expect(hookParams.messageId).toBe(999); + expect(hookParams.success).toBe(true); + }); + + it("preserves Telegram buttons when editing a metadata-driven progress placeholder", async () => { + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { telegram: "Working on it..." }, + }, + result: { + text: "Choose an option", + channelData: { + telegram: { + buttons: [[{ text: "Approve", callback_data: "approve" }]], + }, + }, + }, + }); + + await handler(createPrivateCommandContext({ match: "now" })); + + expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); + const editCall = firstCall( + editMessageTelegram as unknown as { mock: { calls: Array> } }, + ); + expect(editCall[0]).toBe(100); + expect(editCall[1]).toBe(999); + expect(editCall[2]).toBe("Choose an option"); + expect((editCall[3] as { buttons?: unknown } | undefined)?.buttons).toEqual([ + [{ text: "Approve", callback_data: "approve" }], + ]); + expect(deleteMessage).not.toHaveBeenCalled(); + expect(deliverReplies).not.toHaveBeenCalled(); + }); + + it("delivers reactions after cleaning up a metadata-driven progress placeholder", async () => { + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { telegram: "Working on it..." }, + }, + result: { + text: "Command completed successfully", + channelData: { telegram: { reaction: { emoji: "🔥" } } }, + }, + }); + + await handler(createPrivateCommandContext({ match: "now", messageId: 321 })); + + expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); + expect(editMessageTelegram).not.toHaveBeenCalled(); + expect(deleteMessage).toHaveBeenCalledWith(100, 999); + const deliveryParams = firstDeliverRepliesParams(); + expect(deliveryParams.replyToMode).toBe("all"); + expect(replyAt(deliveryParams)).toEqual({ + text: "Command completed successfully", + replyToId: "321", + channelData: { telegram: { reaction: { emoji: "🔥" } } }, + }); + }); + + it("falls back to a normal reply when a metadata-driven progress result is not editable", async () => { + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { telegram: "Working on it..." }, + }, + result: { + text: "rich output", + mediaUrl: "/tmp/render.png", + }, + }); + + await handler( + createPrivateCommandContext({ + match: "now", + }), + ); + + expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); + expect(editMessageTelegram).not.toHaveBeenCalled(); + expect(deleteMessage).toHaveBeenCalledWith(100, 999); + expect(replyAt(firstDeliverRepliesParams()).mediaUrl).toBe("/tmp/render.png"); + }); + + it("falls back to a normal reply when a progress result has presentation controls", async () => { + const presentation = { + blocks: [ + { + type: "buttons", + buttons: [{ label: "Approve", action: { type: "callback", value: "/approve yes" } }], + }, + ], + }; + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { telegram: "Working on it..." }, + }, + result: { + text: "Approval required", + presentation, + }, + }); + + await handler(createPrivateCommandContext({ match: "now" })); + + expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); + expect(editMessageTelegram).not.toHaveBeenCalled(); + expect(deleteMessage).toHaveBeenCalledWith(100, 999); + expect(replyAt(firstDeliverRepliesParams())).toMatchObject({ + text: "Approval required", + presentation, + }); + }); + + it("cleans up the progress placeholder before falling back after an edit failure", async () => { + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { telegram: "Working on it..." }, + }, + result: { + text: "Command completed successfully", + }, + }); + editMessageTelegram.mockRejectedValueOnce(new Error("message to edit not found")); + + await handler(createPrivateCommandContext({ match: "now" })); + + expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); + expect(editMessageTelegram).toHaveBeenCalledTimes(1); + expect(deleteMessage).toHaveBeenCalledWith(100, 999); + expect(replyAt(firstDeliverRepliesParams()).text).toBe("Command completed successfully"); + }); + + it("cleans up the progress placeholder when Telegram suppresses a local exec approval reply", async () => { + const { handler, sendMessage, deleteMessage } = registerPlugCommand({ + args: "now", + command: { + nativeProgressMessages: { telegram: "Working on it..." }, + }, + result: { + text: "Approval required.\n\n```txt\n/approve 7f423fdc allow-once\n```", + channelData: { + execApproval: { + approvalId: "7f423fdc-1111-2222-3333-444444444444", + approvalSlug: "7f423fdc", + allowedDecisions: ["allow-once", "allow-always", "deny"], + }, + }, + }, + cfg: { + channels: { + telegram: { + execApprovals: { + enabled: true, + approvers: ["12345"], + target: "dm", + }, + }, + }, + }, + }); + + await handler(createPrivateCommandContext({ match: "now" })); + + expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); + expect(deleteMessage).toHaveBeenCalledWith(100, 999); + expect(editMessageTelegram).not.toHaveBeenCalled(); + expect(deliverReplies).not.toHaveBeenCalled(); + }); + + it("sends plugin command error replies silently when silentErrorReplies is enabled", async () => { + const { handler } = registerPlugCommand({ + cfg: { + channels: { + telegram: { + silentErrorReplies: true, + }, + }, + }, + result: { + text: "plugin failed", + isError: true, + }, + registerOverrides: { + telegramCfg: { silentErrorReplies: true } as TelegramAccountConfig, + }, + }); + + await handler(createPrivateCommandContext()); + + const deliverParams = firstDeliverRepliesParams(); + expect(deliverParams.silent).toBe(true); + expect(replyAt(deliverParams).isError).toBe(true); + }); + + it("uses rich messages for plugin command replies when enabled", async () => { + const { handler } = registerPlugCommand({ + cfg: { + channels: { + telegram: { + richMessages: true, + }, + }, + }, + registerOverrides: { + telegramCfg: { richMessages: true } as TelegramAccountConfig, + }, + }); + + await handler(createPrivateCommandContext()); + + expect(firstDeliverRepliesParams().richMessages).toBe(true); + }); + + it("forwards topic-scoped binding context to Telegram plugin commands", async () => { + const { handler } = registerPlugCommand(); + + await handler({ + match: "", + message: { + message_id: 2, + date: Math.floor(Date.now() / 1000), + chat: { + id: -1001234567890, + type: "supergroup", + title: "Forum Group", + is_forum: true, + }, + message_thread_id: 77, + from: { id: 200, username: "bob" }, + }, + }); + + const commandParams = firstExecutePluginCommandParams(); + expect(commandParams.channel).toBe("telegram"); + expect(commandParams.accountId).toBe("default"); + expect(commandParams.from).toBe("telegram:group:-1001234567890:topic:77"); + expect(commandParams.to).toBe("telegram:-1001234567890"); + expect(commandParams.messageThreadId).toBe(77); + }); + + it("treats Telegram forum #General commands as topic 1 when Telegram omits topic metadata", async () => { + const getChat = vi.fn(async () => ({ id: -1001234567890, type: "supergroup", is_forum: true })); + const { handler } = registerPlugCommand({ + botHarness: createCommandBot({ api: { getChat } }), + }); + + await handler({ + match: "", + message: { + message_id: 2, + date: Math.floor(Date.now() / 1000), + chat: { + id: -1001234567890, + type: "supergroup", + title: "Forum Group", + }, + from: { id: 200, username: "bob" }, + }, + }); + + expect(getChat).toHaveBeenCalledWith(-1001234567890); + const commandParams = firstExecutePluginCommandParams(); + expect(commandParams.accountId).toBe("default"); + expect(commandParams.from).toBe("telegram:group:-1001234567890:topic:1"); + expect(commandParams.to).toBe("telegram:-1001234567890"); + expect(commandParams.messageThreadId).toBe(1); + }); + + it("forwards direct-message binding context to Telegram plugin commands", async () => { + const { handler } = registerPlugCommand(); + + await handler(createPrivateCommandContext({ chatId: 100, userId: 200 })); + + const commandParams = firstExecutePluginCommandParams(); + expect(commandParams.channel).toBe("telegram"); + expect(commandParams.accountId).toBe("default"); + expect(commandParams.from).toBe("telegram:100"); + expect(commandParams.to).toBe("telegram:100"); + expect(commandParams.messageThreadId).toBeUndefined(); + }); + + it("suppresses the fallback reply when a plugin command returns suppressReply: true", async () => { + const { handler } = registerPlugCommand({ + result: { suppressReply: true }, + }); + + await handler(createPrivateCommandContext()); + + expect(deliverReplies).not.toHaveBeenCalled(); + expect(editMessageTelegram).not.toHaveBeenCalled(); + }); + + it("uses bot topic capability for Telegram plugin command DM topic session keys", async () => { + const { handler } = registerPlugCommand(); + + await handler({ + ...createPrivateCommandContext({ chatId: 100, userId: 200, threadId: 77 }), + me: { has_topics_enabled: true }, + }); + + const commandParams = firstExecutePluginCommandParams(); + expect(commandParams.sessionKey).toBe("agent:main:main:thread:100:77"); + const deliveryParams = firstDeliverRepliesParams(); + expect(deliveryParams.sessionKeyForInternalHooks).toBe("agent:main:main:thread:100:77"); + }); + + it("passes persisted topic session identity to plugin commands", async () => { + pluginSessionMocks.getSessionEntry.mockReturnValue({ + authProfileOverride: "openai:owner@example.com", + sessionId: "sess-topic", + updatedAt: 1, + }); + const { handler } = registerPlugCommand({ + cfg: { commands: { allowFrom: { telegram: ["200"] } } } as OpenClawConfig, + }); + + await handler( + createTelegramTopicCommandContext({ match: "bind --cwd /tmp/work", threadId: 42 }), + ); + + expect(firstExecutePluginCommandParams()).toEqual( + expect.objectContaining({ + sessionKey: "agent:main:telegram:group:-1001234567890:topic:42", + sessionId: "sess-topic", + messageThreadId: 42, + }), + ); + }); + + it.each([ + { + name: "creates a SQLite marker when the entry has no file", + entry: { sessionId: "sess-main", updatedAt: 1 } satisfies SessionEntry, + }, + { + name: "keeps the canonical SQLite marker", + entry: { + sessionId: "sess-main", + sessionFile: "sqlite:main:sess-main:/tmp/openclaw-sessions.json", + updatedAt: 1, + } satisfies SessionEntry, + }, + { + name: "replaces a stale legacy transcript path", + entry: { + sessionId: "sess-main", + sessionFile: "sess-main.jsonl", + updatedAt: 1, + } satisfies SessionEntry, + }, + ])("$name", async ({ entry }) => { + pluginSessionMocks.getSessionEntry.mockReturnValue(entry); + const { handler } = registerPlugCommand(); + + await handler(createPrivateCommandContext({ match: "status" })); + + expect(firstExecutePluginCommandParams()).toEqual( + expect.objectContaining({ + sessionKey: "agent:main:main", + sessionId: "sess-main", + sessionFile: "sqlite:main:sess-main:/tmp/openclaw-sessions.json", + }), + ); + }); + + it("sends an empty-response fallback when a plugin command returns undefined", async () => { + pluginCommandHandler.mockResolvedValueOnce(undefined as never); + const { handler } = registerPlugCommand(); + + await handler(createPrivateCommandContext({ match: "status" })); + + expect(replyAt(firstDeliverRepliesParams())).toEqual({ + text: "No response generated. Please try again.", + }); + }); +}); diff --git a/extensions/telegram/src/bot-native-command-plugins.ts b/extensions/telegram/src/bot-native-command-plugins.ts new file mode 100644 index 000000000000..592f741d98e2 --- /dev/null +++ b/extensions/telegram/src/bot-native-command-plugins.ts @@ -0,0 +1,316 @@ +// Telegram plugin module implements native plugin command behavior. +import { randomUUID } from "node:crypto"; +import type { Bot, Context } from "grammy"; +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; +import type { PluginCommandNativeCandidate } from "openclaw/plugin-sdk/plugin-command-runtime"; +import { hasOutboundReplyContent } from "openclaw/plugin-sdk/reply-payload"; +import { + formatSqliteSessionFileMarker, + getSessionEntry, + resolveStorePath, +} from "openclaw/plugin-sdk/session-store-runtime"; +import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime"; +import { withTelegramApiErrorLogging } from "./api-logging.js"; +import { + prepareTelegramCommandDispatch, + type TelegramCommandExecutorParams, +} from "./bot-native-command-dispatch.js"; +import { + buildTelegramRoutingTarget, + buildTelegramGroupFrom, + buildTelegramThreadParams, + extractTelegramForumFlag, + resolveTelegramForumFlag, + resolveTelegramMessageThreadSpec, +} from "./bot/helpers.js"; +import type { TelegramGetChat } from "./bot/types.js"; +import type { TelegramInlineButtons } from "./button-types.js"; +import { shouldSuppressLocalTelegramExecApprovalPrompt } from "./exec-approvals.js"; +import { buildInlineKeyboard } from "./inline-keyboard.js"; +import { recordSentMessage } from "./sent-message-cache.js"; + +const EMPTY_RESPONSE_FALLBACK = "No response generated. Please try again."; + +type TelegramNativeReplyPayload = import("openclaw/plugin-sdk/plugin-entry").PluginCommandResult; +type TelegramNativeReplyChannelData = { + buttons?: TelegramInlineButtons; + pin?: boolean; + reaction?: { emoji?: unknown }; +}; + +function resolveTelegramNativeReplyChannelData( + result: TelegramNativeReplyPayload, +): TelegramNativeReplyChannelData | undefined { + return result.channelData?.telegram as TelegramNativeReplyChannelData | undefined; +} + +function normalizeTelegramNativeReplyPayload( + result: TelegramNativeReplyPayload | null | undefined, +): TelegramNativeReplyPayload { + return result && typeof result === "object" ? result : {}; +} + +function hasTelegramNativeReplyReaction(result: TelegramNativeReplyPayload): boolean { + const reactionEmoji = resolveTelegramNativeReplyChannelData(result)?.reaction?.emoji; + return typeof reactionEmoji === "string" && reactionEmoji.trim().length > 0; +} + +function hasRenderableTelegramNativeReplyPayload(result: TelegramNativeReplyPayload): boolean { + const { channelData: _channelData, ...portableContent } = result; + if (hasOutboundReplyContent(portableContent, { trimText: true })) { + return true; + } + const telegramData = resolveTelegramNativeReplyChannelData(result); + return Boolean( + buildInlineKeyboard(telegramData?.buttons) || hasTelegramNativeReplyReaction(result), + ); +} + +function isEditableTelegramProgressResult(result: TelegramNativeReplyPayload): boolean { + const telegramData = resolveTelegramNativeReplyChannelData(result); + return Boolean( + typeof result.text === "string" && + result.text.trim() && + !result.mediaUrl && + (!result.mediaUrls || result.mediaUrls.length === 0) && + !result.presentation && + !result.interactive && + !result.btw && + !hasTelegramNativeReplyReaction(result) && + telegramData?.pin !== true, + ); +} + +async function cleanupTelegramProgressPlaceholder(params: { + bot: Bot; + chatId: number; + progressMessageId?: number; + runtime: TelegramCommandExecutorParams["runtime"]; +}): Promise { + if (params.progressMessageId == null) { + return; + } + try { + await withTelegramApiErrorLogging({ + operation: "deleteMessage", + runtime: params.runtime, + fn: () => params.bot.api.deleteMessage(params.chatId, params.progressMessageId!), + }); + } catch { + // Best-effort cleanup before fallback or suppression exits. + } +} + +async function resolveTelegramPluginThreadParams(params: { + msg: NonNullable; + bot: Bot; +}) { + const isGroup = params.msg.chat.type === "group" || params.msg.chat.type === "supergroup"; + const getChat = + typeof params.bot.api.getChat === "function" + ? (params.bot.api.getChat.bind(params.bot.api) as TelegramGetChat) + : undefined; + const isForum = + params.msg.chat.is_direct_messages === true + ? false + : await resolveTelegramForumFlag({ + chatId: params.msg.chat.id, + chatType: params.msg.chat.type, + isGroup, + isForum: extractTelegramForumFlag(params.msg.chat), + isTopicMessage: params.msg.is_topic_message, + getChat, + }); + return buildTelegramThreadParams(resolveTelegramMessageThreadSpec(params.msg, isForum)); +} + +async function resolveTelegramCommandTranscriptContext(params: { + cfg: OpenClawConfig; + agentId: string; + sessionKey: string; +}): Promise<{ sessionId?: string; sessionFile?: string; authProfileId?: string }> { + const sessionKey = params.sessionKey.trim(); + if (!sessionKey) { + return {}; + } + try { + const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); + const entry = getSessionEntry({ agentId: params.agentId, sessionKey, storePath }); + const sessionId = entry?.sessionId?.trim() || randomUUID(); + const sessionFile = formatSqliteSessionFileMarker({ + agentId: params.agentId, + sessionId, + storePath, + }); + const authProfileId = normalizeOptionalString(entry?.authProfileOverride); + return { sessionId, sessionFile, ...(authProfileId ? { authProfileId } : {}) }; + } catch { + return {}; + } +} + +export async function executeTelegramPluginCommand( + params: TelegramCommandExecutorParams & { + commandName: string; + candidate: PluginCommandNativeCandidate; + }, +): Promise { + const commandBody = `/${params.commandName}${params.rawText ? ` ${params.rawText}` : ""}`; + const pluginCommandDispatch = params.candidate.prepareDispatch(params.rawText); + if (pluginCommandDispatch.kind === "non-plugin") { + await withTelegramApiErrorLogging({ + operation: "sendMessage", + runtime: params.runtime, + fn: async () => + await params.bot.api.sendMessage( + params.msg.chat.id, + "Command not found.", + (await resolveTelegramPluginThreadParams(params)) ?? {}, + ), + }); + return; + } + const dispatch = await prepareTelegramCommandDispatch({ + ...params, + requireAuth: params.candidate.requireAuth, + }); + if (!dispatch) { + return; + } + const targetSessionEntry = dispatch.nativeCommandRuntime.getSessionEntry({ + agentId: dispatch.route.agentId, + sessionKey: dispatch.targetSessionKey, + }); + const from = dispatch.isGroup + ? buildTelegramGroupFrom(dispatch.chatId, dispatch.threadSpec.id) + : `telegram:${dispatch.chatId}`; + const to = + dispatch.threadSpec.scope === "direct-messages" + ? buildTelegramRoutingTarget(dispatch.chatId, dispatch.threadSpec) + : `telegram:${dispatch.chatId}`; + const { deliverReplies, emitTelegramMessageSentHooks } = await dispatch.loadDeliveryRuntime(); + let progressMessageId: number | undefined; + if (params.candidate.progressMessage) { + try { + const sent = await withTelegramApiErrorLogging({ + operation: "sendMessage", + runtime: dispatch.runtime, + fn: () => + dispatch.bot.api.sendMessage( + dispatch.chatId, + params.candidate.progressMessage!, + buildTelegramThreadParams(dispatch.threadSpec), + ), + }); + const maybeMessageId = (sent as { message_id?: unknown } | undefined)?.message_id; + if (typeof maybeMessageId === "number") { + progressMessageId = maybeMessageId; + } + } catch { + // Fall back to the normal final reply path if the placeholder send fails. + } + } + const transcriptContext = await resolveTelegramCommandTranscriptContext({ + cfg: dispatch.runtimeCfg, + agentId: dispatch.route.agentId, + sessionKey: dispatch.targetSessionKey, + }); + const result = normalizeTelegramNativeReplyPayload( + await pluginCommandDispatch.execute({ + senderId: dispatch.senderId, + channel: "telegram", + isAuthorizedSender: dispatch.commandAuthorized, + senderIsOwner: dispatch.senderIsOwner, + agentId: dispatch.route.agentId, + sessionKey: dispatch.targetSessionKey, + sessionId: transcriptContext.sessionId, + sessionFile: transcriptContext.sessionFile, + authProfileId: transcriptContext.authProfileId ?? targetSessionEntry?.authProfileOverride, + commandBody, + config: dispatch.runtimeCfg, + from, + to, + accountId: dispatch.accountId, + messageThreadId: dispatch.threadSpec.id, + }), + ); + const suppressReply = + shouldSuppressLocalTelegramExecApprovalPrompt({ + cfg: dispatch.runtimeCfg, + accountId: dispatch.route.accountId, + payload: result, + }) || result.suppressReply === true; + if (suppressReply) { + await cleanupTelegramProgressPlaceholder({ + bot: dispatch.bot, + chatId: dispatch.chatId, + progressMessageId, + runtime: dispatch.runtime, + }); + return; + } + const hasReaction = hasTelegramNativeReplyReaction(result); + const deliverableResult: TelegramNativeReplyPayload = hasRenderableTelegramNativeReplyPayload( + result, + ) + ? hasReaction && !normalizeOptionalString(result.replyToId) + ? { ...result, replyToId: String(dispatch.msg.message_id) } + : result + : { text: EMPTY_RESPONSE_FALLBACK }; + const progressResultText = + typeof deliverableResult.text === "string" && deliverableResult.text.trim().length > 0 + ? deliverableResult.text + : null; + const telegramResultData = resolveTelegramNativeReplyChannelData(deliverableResult); + if ( + progressMessageId != null && + dispatch.telegramDeps.editMessageTelegram && + progressResultText && + isEditableTelegramProgressResult(deliverableResult) + ) { + try { + await dispatch.telegramDeps.editMessageTelegram( + dispatch.chatId, + progressMessageId, + progressResultText, + { + cfg: dispatch.runtimeCfg, + accountId: dispatch.route.accountId, + textMode: "markdown", + linkPreview: dispatch.runtimeTelegramCfg.linkPreview, + buttons: telegramResultData?.buttons, + }, + ); + recordSentMessage(dispatch.chatId, progressMessageId, dispatch.runtimeCfg); + emitTelegramMessageSentHooks({ + sessionKeyForInternalHooks: dispatch.targetSessionKey, + chatId: String(dispatch.chatId), + accountId: dispatch.route.accountId, + content: progressResultText, + success: true, + messageId: progressMessageId, + isGroup: dispatch.isGroup, + groupId: dispatch.isGroup ? String(dispatch.chatId) : undefined, + }); + return; + } catch { + // Fall through to cleanup + normal delivered reply if editing fails. + } + } + await cleanupTelegramProgressPlaceholder({ + bot: dispatch.bot, + chatId: dispatch.chatId, + progressMessageId, + runtime: dispatch.runtime, + }); + await deliverReplies({ + replies: [deliverableResult], + ...dispatch.buildDeliveryBaseOptions({ + sessionKeyForInternalHooks: dispatch.targetSessionKey, + policySessionKey: dispatch.targetSessionKey, + }), + ...(hasReaction ? { replyToMode: "all" as const } : {}), + silent: + dispatch.runtimeTelegramCfg.silentErrorReplies === true && deliverableResult.isError === true, + }); +} diff --git a/extensions/telegram/src/bot-native-commands.delivery.runtime.ts b/extensions/telegram/src/bot-native-commands.delivery.runtime.ts index 1e98bc24ec91..fd81399c8569 100644 --- a/extensions/telegram/src/bot-native-commands.delivery.runtime.ts +++ b/extensions/telegram/src/bot-native-commands.delivery.runtime.ts @@ -1,5 +1,4 @@ // Telegram plugin module implements bot native commandselivery behavior. -import { createChannelMessageReplyPipeline } from "openclaw/plugin-sdk/channel-outbound"; import { deliverReplies, emitTelegramMessageSentHooks } from "./bot/delivery.js"; -export { createChannelMessageReplyPipeline, deliverReplies, emitTelegramMessageSentHooks }; +export { deliverReplies, emitTelegramMessageSentHooks }; diff --git a/extensions/telegram/src/bot-native-commands.runtime.ts b/extensions/telegram/src/bot-native-commands.runtime.ts index a42867b2565d..6eef942b8771 100644 --- a/extensions/telegram/src/bot-native-commands.runtime.ts +++ b/extensions/telegram/src/bot-native-commands.runtime.ts @@ -1,8 +1,5 @@ // Telegram plugin module implements bot native commands behavior. -export { - ensureConfiguredBindingRouteReady, - recordInboundSessionMetaSafe, -} from "openclaw/plugin-sdk/conversation-runtime"; +export { ensureConfiguredBindingRouteReady } from "openclaw/plugin-sdk/conversation-runtime"; export { getAgentScopedMediaLocalRoots } from "openclaw/plugin-sdk/media-runtime"; export { finalizeInboundContext, diff --git a/extensions/telegram/src/bot-native-commands.session-meta.test.ts b/extensions/telegram/src/bot-native-commands.session-meta.test.ts deleted file mode 100644 index 0f351d70b58c..000000000000 --- a/extensions/telegram/src/bot-native-commands.session-meta.test.ts +++ /dev/null @@ -1,2491 +0,0 @@ -import { createChannelPartialDeliveryError } from "openclaw/plugin-sdk/channel-inbound"; -import { - createEmptyPluginRegistry, - withPluginRuntimeRegistryScope, -} from "openclaw/plugin-sdk/channel-test-helpers"; -import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; -import { createDeferred } from "openclaw/plugin-sdk/extension-shared"; -import { getAgentScopedMediaLocalRoots } from "openclaw/plugin-sdk/media-runtime"; -import { registerPluginCommand } from "openclaw/plugin-sdk/plugin-runtime"; -import { resolveChunkMode } from "openclaw/plugin-sdk/reply-dispatch-runtime"; -import { resolveThreadSessionKeys } from "openclaw/plugin-sdk/routing"; -import type { ResolvedAgentRoute } from "openclaw/plugin-sdk/routing"; -import type { SessionEntry } from "openclaw/plugin-sdk/session-store-runtime"; -// Telegram tests cover bot native commands.session meta plugin behavior. -import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures"; -import { beforeEach, describe, expect, it, vi } from "vitest"; -import type { RegisterTelegramHandlerParams } from "./bot-handlers.types.js"; -import type { TelegramNativeCommandDeps } from "./bot-native-command-deps.runtime.js"; -import { - createTelegramGroupCommandContext, - createNativeCommandTestParams, - createTelegramPrivateCommandContext, - createTelegramTopicCommandContext, - type NativeCommandTestParams, -} from "./bot-native-commands.fixture-test-support.js"; -import { runWithTelegramUpdateProcessingFrame } from "./bot-processing-outcome.js"; - -// All mocks scoped to this file only — does not affect bot-native-commands.test.ts - -type ResolveConfiguredBindingRouteFn = - typeof import("openclaw/plugin-sdk/conversation-runtime").resolveConfiguredBindingRoute; -type EnsureConfiguredBindingRouteReadyFn = - typeof import("openclaw/plugin-sdk/conversation-runtime").ensureConfiguredBindingRouteReady; -type DispatchReplyWithBufferedBlockDispatcherFn = - typeof import("openclaw/plugin-sdk/reply-dispatch-runtime").dispatchReplyWithBufferedBlockDispatcher; -type DispatchReplyWithBufferedBlockDispatcherParams = - Parameters[0]; -type DispatchReplyWithBufferedBlockDispatcherResult = Awaited< - ReturnType ->; -type DispatchChannelInboundTurnFn = - typeof import("openclaw/plugin-sdk/channel-inbound").dispatchChannelInboundTurn; -type ResolveCommandArgMenuFn = - typeof import("openclaw/plugin-sdk/command-auth-native").resolveCommandArgMenu; -type DeliverRepliesFn = typeof import("./bot/delivery.js").deliverReplies; -type DeliverRepliesParams = Parameters[0]; -type LoadModelCatalogFn = typeof import("openclaw/plugin-sdk/agent-runtime").loadModelCatalog; -type ResolveDefaultModelForAgentFn = - typeof import("openclaw/plugin-sdk/agent-runtime").resolveDefaultModelForAgent; - -const dispatchReplyResult: DispatchReplyWithBufferedBlockDispatcherResult = { - queuedFinal: false, - counts: {} as DispatchReplyWithBufferedBlockDispatcherResult["counts"], -}; - -const persistentBindingMocks = vi.hoisted(() => ({ - resolveConfiguredBindingRoute: vi.fn(({ route }) => ({ - bindingResolution: null, - route, - })), - ensureConfiguredBindingRouteReady: vi.fn(async () => ({ - ok: true, - })), -})); -const sessionMocks = vi.hoisted(() => ({ - getSessionEntry: vi.fn(), - loadSessionStore: vi.fn(), - recordSessionMetaFromInbound: vi.fn(), - resolveStorePath: vi.fn(), - updateSessionStoreEntry: vi.fn(), -})); -const commandAuthMocks = vi.hoisted(() => ({ - resolveCommandArgMenu: vi.fn(), -})); -const agentRuntimeMocks = vi.hoisted(() => ({ - loadModelCatalog: vi.fn(async () => [ - { - provider: "openai", - id: "gpt-5.5", - name: "GPT-5.5", - reasoning: true, - }, - ]), - resolveDefaultModelForAgent: vi.fn(), -})); -const pluginRuntimeMocks = vi.hoisted(() => ({ - executePluginCommand: vi.fn(async (_params?: unknown) => ({ text: "ok" })), -})); -const replyMocks = vi.hoisted(() => ({ - dispatchReplyWithBufferedBlockDispatcher: vi.fn( - async () => dispatchReplyResult, - ), -})); -const deliveryMocks = vi.hoisted(() => ({ - deliverReplies: vi.fn(async () => ({ delivered: true })), -})); -const dispatchChannelInboundTurnMock = vi.fn(async (plan) => { - const recordTask = sessionMocks.recordSessionMetaFromInbound({ - storePath: sessionMocks.resolveStorePath(plan.cfg.session?.store, { - agentId: plan.route.agentId, - }), - sessionKey: plan.record?.sessionKey ?? plan.ctxPayload.SessionKey ?? plan.route.sessionKey, - ctx: plan.ctxPayload, - }); - const trackedRecordTask = Promise.resolve(recordTask).catch((error: unknown) => - plan.record?.onRecordError?.(error), - ); - plan.record?.trackSessionMetaTask?.(trackedRecordTask); - await plan.afterRecord?.(); - const deliver = async ( - payload: Parameters< - DispatchReplyWithBufferedBlockDispatcherParams["dispatcherOptions"]["deliver"] - >[0], - info: Parameters< - DispatchReplyWithBufferedBlockDispatcherParams["dispatcherOptions"]["deliver"] - >[1], - ) => { - const providerInfo = { - ...info, - onPlatformSendDispatch: async () => undefined, - }; - const result = - "deliverWithProviderMessageSending" in plan.delivery - ? await plan.delivery.deliverWithProviderMessageSending(payload, providerInfo) - : await plan.delivery.deliver(payload, info); - await plan.delivery.onDelivered?.(payload, info, result); - return result; - }; - const dispatchResult = await replyMocks.dispatchReplyWithBufferedBlockDispatcher({ - ctx: plan.ctxPayload, - cfg: plan.cfg, - dispatcherOptions: { - ...plan.dispatcherOptions, - deliver, - onError: plan.delivery.onError, - }, - replyOptions: plan.replyOptions, - }); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult, - }; -}); -const sessionBindingMocks = vi.hoisted(() => ({ - resolveByConversation: vi.fn< - (ref: unknown) => { bindingId: string; targetSessionKey: string } | null - >(() => null), - touch: vi.fn(), -})); -const conversationStoreMocks = vi.hoisted(() => ({ - readChannelAllowFromStore: vi.fn(async () => []), - upsertChannelPairingRequest: vi.fn(async () => ({ code: "PAIRCODE", created: true })), -})); - -vi.mock("openclaw/plugin-sdk/conversation-runtime", async () => { - const actual = await vi.importActual( - "openclaw/plugin-sdk/conversation-runtime", - ); - return { - ...actual, - resolveConfiguredBindingRoute: persistentBindingMocks.resolveConfiguredBindingRoute, - resolveRuntimeConversationBindingRoute: ( - params: Parameters[0], - ) => { - const conversation = - "conversation" in params - ? params.conversation - : { - channel: params.channel, - accountId: params.accountId, - conversationId: params.conversationId, - parentConversationId: params.parentConversationId, - }; - const bindingRecord = sessionBindingMocks.resolveByConversation(conversation); - const boundSessionKey = bindingRecord?.targetSessionKey?.trim(); - if (!bindingRecord || !boundSessionKey) { - return { bindingRecord: null, route: params.route }; - } - sessionBindingMocks.touch(bindingRecord.bindingId, undefined); - return { - bindingRecord, - boundSessionKey, - boundAgentId: params.route.agentId, - route: { - ...params.route, - sessionKey: boundSessionKey, - lastRoutePolicy: boundSessionKey === params.route.mainSessionKey ? "main" : "session", - matchedBy: "binding.channel", - }, - }; - }, - ensureConfiguredBindingRouteReady: persistentBindingMocks.ensureConfiguredBindingRouteReady, - recordInboundSessionMetaSafe: vi.fn( - async (params: { - cfg: OpenClawConfig; - agentId: string; - sessionKey: string; - ctx: unknown; - onError?: (error: unknown) => void; - }) => { - const storePath = sessionMocks.resolveStorePath(params.cfg.session?.store, { - agentId: params.agentId, - }); - try { - await sessionMocks.recordSessionMetaFromInbound({ - storePath, - sessionKey: params.sessionKey, - ctx: params.ctx, - }); - } catch (error) { - params.onError?.(error); - } - }, - ), - readChannelAllowFromStore: conversationStoreMocks.readChannelAllowFromStore, - upsertChannelPairingRequest: conversationStoreMocks.upsertChannelPairingRequest, - getSessionBindingService: () => ({ - bind: vi.fn(), - getCapabilities: vi.fn(), - listBySession: vi.fn(), - resolveByConversation: (ref: unknown) => sessionBindingMocks.resolveByConversation(ref), - touch: (bindingId: string, at?: number) => sessionBindingMocks.touch(bindingId, at), - unbind: vi.fn(), - }), - }; -}); -vi.mock("openclaw/plugin-sdk/session-store-runtime", async () => { - const actual = await vi.importActual( - "openclaw/plugin-sdk/session-store-runtime", - ); - return { - ...actual, - getSessionEntry: sessionMocks.getSessionEntry, - loadSessionStore: sessionMocks.loadSessionStore, - resolveStorePath: sessionMocks.resolveStorePath, - updateSessionStoreEntry: sessionMocks.updateSessionStoreEntry, - }; -}); -vi.mock("openclaw/plugin-sdk/command-auth-native", async () => { - const actual = await vi.importActual( - "openclaw/plugin-sdk/command-auth-native", - ); - commandAuthMocks.resolveCommandArgMenu.mockImplementation(actual.resolveCommandArgMenu); - return { - ...actual, - resolveCommandArgMenu: commandAuthMocks.resolveCommandArgMenu, - }; -}); -vi.mock("openclaw/plugin-sdk/agent-runtime", async () => { - const actual = await vi.importActual( - "openclaw/plugin-sdk/agent-runtime", - ); - agentRuntimeMocks.resolveDefaultModelForAgent.mockImplementation( - actual.resolveDefaultModelForAgent, - ); - return { - ...actual, - loadPreparedModelCatalog: agentRuntimeMocks.loadModelCatalog, - resolveDefaultModelForAgent: agentRuntimeMocks.resolveDefaultModelForAgent, - }; -}); -vi.mock("./bot-native-commands.runtime.js", () => { - return { - ensureConfiguredBindingRouteReady: persistentBindingMocks.ensureConfiguredBindingRouteReady, - finalizeInboundContext: vi.fn((ctx: unknown) => ctx), - getAgentScopedMediaLocalRoots, - getSessionEntry: sessionMocks.getSessionEntry, - recordInboundSessionMetaSafe: vi.fn( - async (params: { - cfg: OpenClawConfig; - agentId: string; - sessionKey: string; - ctx: unknown; - onError?: (error: unknown) => void; - }) => { - const storePath = sessionMocks.resolveStorePath(params.cfg.session?.store, { - agentId: params.agentId, - }); - try { - await sessionMocks.recordSessionMetaFromInbound({ - storePath, - sessionKey: params.sessionKey, - ctx: params.ctx, - }); - } catch (error) { - params.onError?.(error); - } - }, - ), - resolveChunkMode, - resolveThreadSessionKeys, - dispatchChannelInboundTurn: dispatchChannelInboundTurnMock as unknown as NonNullable< - TelegramNativeCommandDeps["dispatchChannelInboundTurn"] - >, - }; -}); -vi.mock("./bot/delivery.js", () => ({ - deliverReplies: deliveryMocks.deliverReplies, -})); -vi.mock("./bot/delivery.replies.js", () => ({ - deliverReplies: deliveryMocks.deliverReplies, -})); - -let activePluginRegistry: ReturnType; - -type TelegramCommandHandler = (ctx: unknown) => Promise; -type TelegramPluginCommandSpecs = Array<{ - name: string; - description: string; - acceptsArgs?: boolean; -}>; -type TelegramLoginFlow = NonNullable; - -function registerAndResolveStatusHandler(params: { - cfg: OpenClawConfig; - runtimeCfg?: OpenClawConfig; - allowFrom?: string[]; - groupAllowFrom?: string[]; - storeAllowFrom?: string[]; - telegramCfg?: NativeCommandTestParams["telegramCfg"]; - resolveTelegramGroupConfig?: RegisterTelegramHandlerParams["resolveTelegramGroupConfig"]; -}): { - handler: TelegramCommandHandler; - sendMessage: ReturnType; -} { - const { - cfg, - runtimeCfg, - allowFrom, - groupAllowFrom, - storeAllowFrom, - telegramCfg, - resolveTelegramGroupConfig, - } = params; - return registerAndResolveCommandHandlerBase({ - commandName: "status", - cfg, - runtimeCfg, - allowFrom: allowFrom ?? ["*"], - groupAllowFrom: groupAllowFrom ?? [], - storeAllowFrom, - telegramCfg, - resolveTelegramGroupConfig, - }); -} - -function registerAndResolveCommandHandlerBase(params: { - commandName: string; - cfg: OpenClawConfig; - runtimeCfg?: OpenClawConfig; - allowFrom: string[]; - groupAllowFrom: string[]; - storeAllowFrom?: string[]; - telegramCfg?: NativeCommandTestParams["telegramCfg"]; - resolveTelegramGroupConfig?: RegisterTelegramHandlerParams["resolveTelegramGroupConfig"]; - pluginCommandSpecs?: TelegramPluginCommandSpecs; - runModelsAuthLoginFlow?: TelegramLoginFlow; -}): { - handler: TelegramCommandHandler; - sendMessage: ReturnType; -} { - const { - commandName, - cfg, - runtimeCfg, - allowFrom, - groupAllowFrom, - storeAllowFrom, - telegramCfg, - resolveTelegramGroupConfig, - pluginCommandSpecs, - runModelsAuthLoginFlow, - } = params; - const commandHandlers = new Map(); - const sendMessage = vi.fn().mockResolvedValue(undefined); - const baseRuntimeCfg = runtimeCfg ?? cfg; - const commandRuntimeCfg = baseRuntimeCfg; - const telegramDeps: TelegramNativeCommandDeps = { - getRuntimeConfig: vi.fn(() => commandRuntimeCfg), - readChannelAllowFromStore: vi.fn(async () => storeAllowFrom ?? []), - dispatchChannelInboundTurn: dispatchChannelInboundTurnMock as unknown as NonNullable< - TelegramNativeCommandDeps["dispatchChannelInboundTurn"] - >, - listSkillCommandsForAgents: vi.fn(() => []), - syncTelegramMenuCommands: vi.fn(), - sendMessageTelegram: vi.fn(async (_to, text) => { - await sendMessage(100, text, {}); - return { messageId: "999", chatId: "100" }; - }), - ...(runModelsAuthLoginFlow ? { runModelsAuthLoginFlow } : {}), - }; - withPluginRuntimeRegistryScope(activePluginRegistry, () => { - for (const spec of pluginCommandSpecs ?? []) { - expect( - registerPluginCommand(`test-${spec.name}`, { - ...spec, - requireAuth: true, - handler: pluginRuntimeMocks.executePluginCommand, - }), - ).toEqual({ ok: true }); - } - registerTelegramNativeCommands({ - ...createNativeCommandTestParams({ - bot: { - api: { - setMyCommands: vi.fn().mockResolvedValue(undefined), - sendMessage, - }, - command: vi.fn((name: string, cb: TelegramCommandHandler) => { - commandHandlers.set(name, cb); - }), - } as unknown as NativeCommandTestParams["bot"], - cfg, - allowFrom, - groupAllowFrom, - telegramCfg, - resolveTelegramGroupConfig, - telegramDeps, - }), - }); - }); - - const handler = commandHandlers.get(commandName); - if (!handler) { - throw new Error(`expected ${commandName} command handler to be registered`); - } - return { handler, sendMessage }; -} - -function registerAndResolveCommandHandler(params: { - commandName: string; - cfg: OpenClawConfig; - allowFrom?: string[]; - groupAllowFrom?: string[]; - storeAllowFrom?: string[]; - telegramCfg?: NativeCommandTestParams["telegramCfg"]; - resolveTelegramGroupConfig?: RegisterTelegramHandlerParams["resolveTelegramGroupConfig"]; - pluginCommandSpecs?: TelegramPluginCommandSpecs; - runModelsAuthLoginFlow?: TelegramLoginFlow; -}): { - handler: TelegramCommandHandler; - sendMessage: ReturnType; -} { - const { - commandName, - cfg, - allowFrom, - groupAllowFrom, - storeAllowFrom, - telegramCfg, - resolveTelegramGroupConfig, - pluginCommandSpecs, - runModelsAuthLoginFlow, - } = params; - return registerAndResolveCommandHandlerBase({ - commandName, - cfg, - allowFrom: allowFrom ?? [], - groupAllowFrom: groupAllowFrom ?? [], - storeAllowFrom, - telegramCfg, - resolveTelegramGroupConfig, - pluginCommandSpecs, - runModelsAuthLoginFlow, - }); -} - -function createConfiguredAcpTopicBinding(boundSessionKey: string) { - return { - spec: { - channel: "telegram", - accountId: "default", - conversationId: "-1001234567890:topic:42", - parentConversationId: "-1001234567890", - agentId: "codex", - mode: "persistent", - }, - record: { - bindingId: "config:acp:telegram:default:-1001234567890:topic:42", - targetSessionKey: boundSessionKey, - targetKind: "session", - conversation: { - channel: "telegram", - accountId: "default", - conversationId: "-1001234567890:topic:42", - parentConversationId: "-1001234567890", - }, - status: "active", - boundAt: 0, - }, - } as const; -} - -function createConfiguredBindingRoute( - route: ResolvedAgentRoute, - binding: ReturnType | null, -) { - return { - bindingResolution: binding - ? { - conversation: binding.record.conversation, - compiledBinding: { - channel: "telegram" as const, - binding: { - type: "acp" as const, - agentId: binding.spec.agentId, - match: { - channel: "telegram", - accountId: binding.spec.accountId, - peer: { - kind: "group" as const, - id: binding.spec.conversationId, - }, - }, - acp: { - mode: binding.spec.mode, - }, - }, - bindingConversationId: binding.spec.conversationId, - target: { - conversationId: binding.spec.conversationId, - ...(binding.spec.parentConversationId - ? { parentConversationId: binding.spec.parentConversationId } - : {}), - }, - agentId: binding.spec.agentId, - provider: { - compileConfiguredBinding: () => ({ - conversationId: binding.spec.conversationId, - ...(binding.spec.parentConversationId - ? { parentConversationId: binding.spec.parentConversationId } - : {}), - }), - matchInboundConversation: () => ({ - conversationId: binding.spec.conversationId, - ...(binding.spec.parentConversationId - ? { parentConversationId: binding.spec.parentConversationId } - : {}), - }), - }, - targetFactory: { - driverId: "acp" as const, - materialize: () => ({ - record: binding.record, - statefulTarget: { - kind: "stateful" as const, - driverId: "acp" as const, - sessionKey: binding.record.targetSessionKey, - agentId: binding.spec.agentId, - }, - }), - }, - }, - match: { - conversationId: binding.spec.conversationId, - ...(binding.spec.parentConversationId - ? { parentConversationId: binding.spec.parentConversationId } - : {}), - }, - record: binding.record, - statefulTarget: { - kind: "stateful" as const, - driverId: "acp" as const, - sessionKey: binding.record.targetSessionKey, - agentId: binding.spec.agentId, - }, - } - : null, - ...(binding ? { boundSessionKey: binding.record.targetSessionKey } : {}), - route, - }; -} - -function requireValue(value: T | null | undefined, label: string): T { - if (value == null) { - throw new Error(`expected ${label}`); - } - return value; -} - -const requireRecord = createRequireRecord("record", "expected-label-object"); - -function firstMockArg(mockFn: ReturnType, label: string, callIndex = 0): unknown { - const call = mockFn.mock.calls.at(callIndex); - if (!call) { - throw new Error(`expected ${label} call ${callIndex}`); - } - return call.at(0); -} - -function expectRecordFields( - value: unknown, - expected: Record, - label: string, -): Record { - const record = requireRecord(value, label); - for (const [key, expectedValue] of Object.entries(expected)) { - expect(record[key], `${label}.${key}`).toEqual(expectedValue); - } - return record; -} - -function expectSendMessageCall(params: { - sendMessage: ReturnType; - callIndex?: number; - chatId: unknown; - text?: string; - textIncludes?: string; - optionFields?: Record; - requireReplyMarkup?: boolean; - label: string; -}): Record { - const call = requireValue( - params.sendMessage.mock.calls[params.callIndex ?? 0], - `${params.label} sendMessage call`, - ); - expect(call[0]).toBe(params.chatId); - if (params.text !== undefined) { - expect(call[1]).toBe(params.text); - } - if (params.textIncludes !== undefined) { - expect(String(call[1])).toContain(params.textIncludes); - } - const options = params.optionFields - ? expectRecordFields(call[2], params.optionFields, `${params.label} sendMessage options`) - : requireRecord(call[2], `${params.label} sendMessage options`); - if (params.requireReplyMarkup) { - requireRecord(options.reply_markup, `${params.label} reply markup`); - } - return options; -} - -function expectUnauthorizedNewCommandBlocked(sendMessage: ReturnType) { - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - expect(persistentBindingMocks.resolveConfiguredBindingRoute).not.toHaveBeenCalled(); - expect(persistentBindingMocks.ensureConfiguredBindingRouteReady).not.toHaveBeenCalled(); - expectSendMessageCall({ - sendMessage, - chatId: -1001234567890, - text: "You are not authorized to use this command.", - optionFields: { message_thread_id: 42 }, - label: "unauthorized /new", - }); -} - -function resetSessionMetaMocks() { - persistentBindingMocks.resolveConfiguredBindingRoute.mockClear(); - persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => - createConfiguredBindingRoute(route, null), - ); - persistentBindingMocks.ensureConfiguredBindingRouteReady.mockClear(); - persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ ok: true }); - commandAuthMocks.resolveCommandArgMenu.mockClear().mockImplementation(({ command, args }) => { - if (args?.raw || (args?.values && Object.keys(args.values).length > 0)) { - return null; - } - const arg = command.args?.[0]; - if (!arg) { - return null; - } - if (command.key === "think") { - return { - arg, - choices: ["low", "medium", "high"].map((value) => ({ label: value, value })), - }; - } - if (command.key === "fast") { - const choices = ["on", "off", "auto (30 sec)", "default", "status"]; - return { - arg, - choices: choices.map((value) => ({ label: value, value })), - }; - } - return null; - }); - agentRuntimeMocks.loadModelCatalog.mockClear().mockResolvedValue([ - { - provider: "openai", - id: "gpt-5.5", - name: "GPT-5.5", - reasoning: true, - }, - ]); - sessionMocks.getSessionEntry.mockClear().mockReturnValue(undefined); - sessionMocks.loadSessionStore.mockClear().mockReturnValue({}); - sessionMocks.getSessionEntry.mockImplementation( - ({ storePath, sessionKey }: { storePath: string; sessionKey: string }) => - sessionMocks.loadSessionStore(storePath)[sessionKey], - ); - sessionMocks.updateSessionStoreEntry.mockClear().mockImplementation(async (params) => { - const current = sessionMocks.loadSessionStore(params.storePath)[params.sessionKey]; - if (!current) { - return null; - } - const patch = await params.update({ ...current }); - return patch ? { ...current, ...patch } : current; - }); - sessionMocks.recordSessionMetaFromInbound.mockClear().mockResolvedValue(undefined); - sessionMocks.resolveStorePath.mockClear().mockReturnValue("/tmp/openclaw-sessions.json"); - pluginRuntimeMocks.executePluginCommand.mockClear().mockResolvedValue({ text: "ok" }); - activePluginRegistry = createEmptyPluginRegistry(); - replyMocks.dispatchReplyWithBufferedBlockDispatcher - .mockClear() - .mockResolvedValue(dispatchReplyResult); - dispatchChannelInboundTurnMock.mockClear(); - sessionBindingMocks.resolveByConversation.mockReset().mockReturnValue(null); - sessionBindingMocks.touch.mockReset(); - deliveryMocks.deliverReplies.mockClear().mockResolvedValue({ delivered: true }); -} - -activePluginRegistry = createEmptyPluginRegistry(); -const { registerTelegramNativeCommands } = await import("./bot-native-commands.js"); -await import("./bot-native-commands.runtime.js"); -agentRuntimeMocks.resolveDefaultModelForAgent({ cfg: {}, agentId: "main" }); -resetSessionMetaMocks(); -const warmStatusHandler = registerAndResolveStatusHandler({ cfg: {} }); -await warmStatusHandler.handler(createTelegramPrivateCommandContext()); - -describe("registerTelegramNativeCommands — session metadata", () => { - beforeEach(resetSessionMetaMocks); - - it("calls recordSessionMetaFromInbound after a native slash command", async () => { - const shadowHandler = vi.fn(async () => ({ text: "wrong plugin" })); - activePluginRegistry.commands.push({ - pluginId: "shadow-plugin", - source: "test", - command: { - name: "status", - description: "Shadow status", - channels: ["telegram"], - requireAuth: false, - handler: shadowHandler, - }, - }); - const cfg: OpenClawConfig = {}; - const { handler } = registerAndResolveStatusHandler({ cfg }); - await handler(createTelegramPrivateCommandContext()); - - expect(sessionMocks.recordSessionMetaFromInbound).toHaveBeenCalledTimes(1); - expect(shadowHandler).not.toHaveBeenCalled(); - const turnPlan = dispatchChannelInboundTurnMock.mock.calls[0]?.[0]; - expect(turnPlan?.replyOptions?.[Symbol.for("openclaw.pluginCommandDispatch") as never]).toEqual( - { kind: "non-plugin" }, - ); - const call = ( - sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< - [{ sessionKey?: string; ctx?: { OriginatingChannel?: string; Provider?: string } }] - > - )[0]?.[0]; - expect(call?.ctx?.OriginatingChannel).toBe("telegram"); - expect(call?.ctx?.Provider).toBe("telegram"); - expect(call?.sessionKey).toBe(turnPlan?.ctxPayload.CommandTargetSessionKey); - expect(turnPlan?.record?.sessionKey).toBe(turnPlan?.ctxPayload.CommandTargetSessionKey); - }); - - it("leaves native-command outcomes to the update middleware owner", async () => { - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - const { result } = await runWithTelegramUpdateProcessingFrame(async () => { - await handler(createTelegramPrivateCommandContext()); - }); - - expect(result).toBeUndefined(); - }); - - it("preserves every argument on native queue command turns", async () => { - const { handler } = registerAndResolveCommandHandler({ - commandName: "queue", - cfg: {}, - allowFrom: ["*"], - }); - - await handler(createTelegramPrivateCommandContext({ match: "Can you diagnose this?" })); - - expect(dispatchChannelInboundTurnMock).toHaveBeenCalledWith( - expect.objectContaining({ - ctxPayload: expect.objectContaining({ - Body: "/queue Can you diagnose this?", - CommandBody: "/queue Can you diagnose this?", - CommandTurn: expect.objectContaining({ - kind: "native", - body: "/queue Can you diagnose this?", - }), - }), - }), - ); - }); - - it("keeps one live config snapshot through native command execution", async () => { - const startupCfg: OpenClawConfig = { session: { store: "/tmp/startup-sessions.json" } }; - const runtimeCfg: OpenClawConfig = { session: { store: "/tmp/runtime-sessions.json" } }; - const { handler } = registerAndResolveStatusHandler({ cfg: startupCfg, runtimeCfg }); - - await handler(createTelegramPrivateCommandContext()); - - const dispatchCall = requireRecord( - firstMockArg( - replyMocks.dispatchReplyWithBufferedBlockDispatcher, - "dispatchReplyWithBufferedBlockDispatcher", - ), - "dispatch call", - ); - expect(dispatchCall.cfg).toBe(runtimeCfg); - }); - - it.each([ - { blockStreamingEnabled: false, expectedDisableBlockStreaming: true }, - { blockStreamingEnabled: true, expectedDisableBlockStreaming: false }, - ])( - "uses nested streaming.block.enabled=$blockStreamingEnabled for native command dispatch", - async ({ blockStreamingEnabled, expectedDisableBlockStreaming }) => { - const cfg = { - channels: { - telegram: { - streaming: { block: { enabled: blockStreamingEnabled } }, - }, - }, - } satisfies OpenClawConfig; - const { handler } = registerAndResolveStatusHandler({ cfg }); - - await handler(createTelegramPrivateCommandContext()); - - const dispatchCall = requireRecord( - firstMockArg( - replyMocks.dispatchReplyWithBufferedBlockDispatcher, - "dispatchReplyWithBufferedBlockDispatcher", - ), - "dispatch call", - ); - expect(dispatchCall.replyOptions).toMatchObject({ - disableBlockStreaming: expectedDisableBlockStreaming, - }); - }, - ); - - it("uses the target session model when building native argument menus", async () => { - const cfg = { - agents: { - defaults: { - thinkingDefault: "low", - models: { - "anthropic/claude-opus-4-7": { - params: { thinking: "xhigh" }, - }, - }, - }, - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - providerOverride: "anthropic", - modelOverride: "claude-opus-4-7", - modelOverrideSource: "user", - thinkingLevel: "high", - updatedAt: 0, - }, - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "think" && params.provider === "anthropic", - )?.[0]; - expectRecordFields( - menuCall, - { provider: "anthropic", model: "claude-opus-4-7" }, - "thinking menu call", - ); - expect(sessionMocks.getSessionEntry).toHaveBeenCalledWith({ - storePath: "/tmp/openclaw-sessions.json", - sessionKey: "agent:main:main", - }); - expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: "Current thinking level: high.\nChoose level for /think.", - requireReplyMarkup: true, - label: "thinking menu", - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it.each([ - { sessionRuntime: undefined, expectedRuntime: "codex" }, - { sessionRuntime: "openclaw", expectedRuntime: "openclaw" }, - ])( - "uses the effective $expectedRuntime runtime for native /think menus", - async ({ sessionRuntime, expectedRuntime }) => { - const cfg = { - agents: { - defaults: { - models: { - "openai/gpt-5.6-luna": { agentRuntime: { id: "codex" } }, - }, - }, - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - providerOverride: "openai", - modelOverride: "gpt-5.6-luna", - modelOverrideSource: "user", - ...(sessionRuntime ? { agentRuntimeOverride: sessionRuntime } : {}), - updatedAt: 0, - }, - }); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "think" && params.model === "gpt-5.6-luna", - )?.[0]; - expectRecordFields( - menuCall, - { - provider: "openai", - model: "gpt-5.6-luna", - agentRuntime: expectedRuntime, - }, - "runtime-aware thinking menu call", - ); - }, - ); - - it("resolves /think menu choices against the runtime catalog for live-discovered models", async () => { - const cfg = { - agents: { defaults: { models: { "ollama/*": {} } } }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - providerOverride: "ollama", - modelOverride: "glm-5.2:cloud", - modelOverrideSource: "user", - updatedAt: 0, - }, - }); - const runtimeCatalog = [ - { provider: "ollama", id: "glm-5.2:cloud", name: "glm-5.2:cloud", reasoning: true }, - ]; - agentRuntimeMocks.loadModelCatalog.mockClear().mockResolvedValue(runtimeCatalog); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "think" && params.provider === "ollama", - )?.[0]; - const menuRecord = expectRecordFields( - menuCall, - { provider: "ollama", model: "glm-5.2:cloud" }, - "ollama thinking menu call", - ); - expect(agentRuntimeMocks.loadModelCatalog).toHaveBeenCalled(); - expect(menuRecord.catalog).toEqual(runtimeCatalog); - }); - - it("loads the runtime catalog for /think when no session model override is set", async () => { - const cfg = { - agents: { defaults: { model: "ollama/glm-5.2:cloud", models: { "ollama/*": {} } } }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({}); - const runtimeCatalog = [ - { provider: "ollama", id: "glm-5.2:cloud", name: "glm-5.2:cloud", reasoning: true }, - ]; - agentRuntimeMocks.loadModelCatalog.mockClear().mockResolvedValue(runtimeCatalog); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - expect(agentRuntimeMocks.loadModelCatalog).toHaveBeenCalled(); - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "think", - )?.[0]; - const menuRecord = expectRecordFields(menuCall, {}, "default-model thinking menu call"); - expect(menuRecord.provider).toBeUndefined(); - expect(menuRecord.catalog).toEqual(runtimeCatalog); - }); - - it("inherits the parent session model when building DM thread native argument menus", async () => { - const cfg: OpenClawConfig = {}; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - providerOverride: "anthropic", - modelOverride: "claude-opus-4-7", - modelOverrideSource: "user", - updatedAt: 0, - }, - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext({ threadId: 77 })); - - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "think" && params.provider === "anthropic", - )?.[0]; - expectRecordFields( - menuCall, - { provider: "anthropic", model: "claude-opus-4-7" }, - "thread thinking menu call", - ); - expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: "Choose level for /think.", - requireReplyMarkup: true, - label: "thread thinking menu", - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it("uses the configured default model instead of temporary auto fallback overrides", async () => { - const cfg = { - agents: { - defaults: { - model: { primary: "openai/gpt-5.5" }, - thinkingDefault: "medium", - }, - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - providerOverride: "anthropic", - modelOverride: "claude-opus-4-7", - modelOverrideSource: "auto", - modelProvider: "anthropic", - model: "claude-opus-4-7", - updatedAt: 0, - }, - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "think" && params.provider === "openai", - )?.[0]; - expectRecordFields( - menuCall, - { provider: "openai", model: "gpt-5.5" }, - "default model thinking menu call", - ); - expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: "Current thinking level: medium.\nChoose level for /think.", - requireReplyMarkup: true, - label: "default model thinking menu", - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it("uses configured model defaults instead of runtime auth metadata for the fast menu", async () => { - const cfg = { - agents: { - defaults: { - model: { primary: "openai/gpt-5.5" }, - models: { - "openai/gpt-5.5": { - params: { fastMode: "auto", fastAutoOnSeconds: 30 }, - }, - }, - }, - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - modelProvider: "openai-codex", - model: "gpt-5.5", - updatedAt: 0, - }, - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "fast", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - const menuCall = commandAuthMocks.resolveCommandArgMenu.mock.calls.find( - ([params]) => params.command.key === "fast", - )?.[0]; - expectRecordFields(menuCall, { cfg }, "fast menu call"); - expect( - commandAuthMocks.resolveCommandArgMenu.mock.calls.some( - ([params]) => - params.command.key === "fast" && - params.provider === "openai" && - params.model === "gpt-5.5", - ), - ).toBe(true); - const options = expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: - "Current fast mode: auto (30 sec) (default: model).\nOptions: on, off, auto (30 sec), default, status.", - requireReplyMarkup: true, - label: "fast menu", - }); - const replyMarkup = options.reply_markup as - | { inline_keyboard?: Array> } - | undefined; - const labels = (replyMarkup?.inline_keyboard ?? []).flatMap((row) => - row.map((button) => button.text), - ); - expect(labels).toContain("auto (30 sec)"); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it("uses the read-only catalog for Claude CLI thinking menus", async () => { - const cfg = { - agents: { - defaults: { - model: { primary: "anthropic/claude-opus-4-8" }, - }, - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({}); - agentRuntimeMocks.loadModelCatalog.mockImplementation(async (params) => { - if (!params?.readOnly) { - throw new Error("native /think must not start full model discovery"); - } - return [ - { - provider: "anthropic", - id: "claude-opus-4-8", - name: "Claude Opus 4.8", - reasoning: true, - }, - ]; - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - expect(agentRuntimeMocks.loadModelCatalog).toHaveBeenCalledWith( - expect.objectContaining({ - config: cfg, - agentDir: expect.any(String), - readOnly: true, - }), - ); - expect(agentRuntimeMocks.loadModelCatalog.mock.calls[0]?.[0]).not.toHaveProperty( - "workspaceDir", - ); - expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: "Current thinking level: off.\nChoose level for /think.", - requireReplyMarkup: true, - label: "Claude CLI thinking menu", - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it("uses target model thinking defaults before global thinking defaults", async () => { - const cfg = { - agents: { - defaults: { - thinkingDefault: "low", - models: { - "anthropic/claude-opus-4-7": { - params: { thinking: "xhigh" }, - }, - }, - }, - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - providerOverride: "anthropic", - modelOverride: "claude-opus-4-7", - modelOverrideSource: "user", - updatedAt: 0, - }, - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: "Current thinking level: xhigh.\nChoose level for /think.", - requireReplyMarkup: true, - label: "target model thinking menu", - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it("uses per-agent thinking defaults before target model and global thinking defaults", async () => { - const cfg = { - agents: { - defaults: { - thinkingDefault: "low", - models: { - "anthropic/claude-opus-4-7": { - params: { thinking: "xhigh" }, - }, - }, - }, - list: [ - { - id: "alpha", - model: { primary: "anthropic/claude-opus-4-7" }, - thinkingDefault: "minimal", - }, - ], - }, - } as OpenClawConfig; - sessionMocks.loadSessionStore.mockReturnValue({}); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "think", - cfg, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext()); - - expectSendMessageCall({ - sendMessage, - chatId: 100, - textIncludes: "Current thinking level: minimal.\nChoose level for /think.", - requireReplyMarkup: true, - label: "agent thinking menu", - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - }); - - it("does not load the session store when a native argument menu is skipped", async () => { - const { handler } = registerAndResolveCommandHandler({ - commandName: "think", - cfg: {}, - allowFrom: ["*"], - }); - await handler(createTelegramPrivateCommandContext({ match: "high" })); - - expect(sessionMocks.loadSessionStore).not.toHaveBeenCalled(); - expect(agentRuntimeMocks.loadModelCatalog).not.toHaveBeenCalled(); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1); - }); - - it("awaits routed session metadata persistence before command dispatch", async () => { - const deferred = createDeferred(); - sessionMocks.recordSessionMetaFromInbound.mockReturnValue(deferred.promise); - - const cfg: OpenClawConfig = {}; - const { handler } = registerAndResolveStatusHandler({ cfg }); - const runPromise = handler(createTelegramPrivateCommandContext()); - - await vi.waitFor(() => { - expect(sessionMocks.recordSessionMetaFromInbound).toHaveBeenCalledTimes(1); - }); - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - - deferred.resolve(); - await runPromise; - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledTimes(1); - - const dispatcherOptions = requireRecord( - requireRecord( - firstMockArg( - replyMocks.dispatchReplyWithBufferedBlockDispatcher, - "dispatchReplyWithBufferedBlockDispatcher", - ), - "dispatch reply params", - ).dispatcherOptions, - "dispatcher options", - ); - expect(dispatcherOptions.beforeDeliver).toBeTypeOf("function"); - }); - - it("does not inject approval buttons for native command replies once the monitor owns approvals", async () => { - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce( - async ({ dispatcherOptions }: DispatchReplyWithBufferedBlockDispatcherParams) => { - await dispatcherOptions.deliver( - { - text: "Mode: foreground\nRun: /approve 7f423fdc allow-once (or allow-always / deny).", - }, - { kind: "final" }, - ); - return dispatchReplyResult; - }, - ); - - const { handler } = registerAndResolveStatusHandler({ - cfg: { - channels: { - telegram: { - execApprovals: { - enabled: true, - approvers: ["12345"], - target: "dm", - }, - }, - }, - }, - }); - await handler(createTelegramPrivateCommandContext()); - - const deliveredCall = firstMockArg(deliveryMocks.deliverReplies, "deliverReplies") as - | DeliverRepliesParams - | undefined; - const deliveredPayload = deliveredCall?.replies?.[0]; - if (!deliveredPayload) { - throw new Error("expected approval reply payload to be delivered"); - } - expect(deliveredPayload?.["text"]).toContain("/approve 7f423fdc allow-once"); - expect(deliveredPayload?.["channelData"]).toBeUndefined(); - }); - - it("suppresses local structured exec approval replies for native commands", async () => { - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce( - async ({ dispatcherOptions }: DispatchReplyWithBufferedBlockDispatcherParams) => { - await dispatcherOptions.deliver( - { - text: "Approval required.\n\n```txt\n/approve 7f423fdc allow-once\n```", - channelData: { - execApproval: { - approvalId: "7f423fdc-1111-2222-3333-444444444444", - approvalSlug: "7f423fdc", - allowedDecisions: ["allow-once", "allow-always", "deny"], - }, - }, - }, - { kind: "tool" }, - ); - return dispatchReplyResult; - }, - ); - - const { handler } = registerAndResolveStatusHandler({ - cfg: { - channels: { - telegram: { - execApprovals: { - enabled: true, - approvers: ["12345"], - target: "dm", - }, - }, - }, - }, - }); - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); - }); - - it("does not emit the empty fallback when reply-payload hooks cancel a native reply", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - await plan.delivery.onDelivered?.( - { text: "cancelled" }, - { kind: "final" }, - { - visibleReplySent: false, - suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, - }, - ); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); - }); - - it("does not emit the empty fallback for a message-tool-only native reply", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - plan.dispatcherOptions?.onSkip?.({}, { kind: "final", reason: "empty" }); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - sourceReplyDeliveryMode: "message_tool_only", - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); - }); - - it("retains the native fallback when message-tool-only delivery also fails", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - plan.dispatcherOptions?.onSkip?.({}, { kind: "final", reason: "empty" }); - plan.delivery.onError?.(new Error("Telegram final delivery failed"), { - kind: "final", - }); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - sourceReplyDeliveryMode: "message_tool_only", - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); - expect(deliveryMocks.deliverReplies).toHaveBeenCalledWith( - expect.objectContaining({ - replies: [{ text: "No response generated. Please try again." }], - }), - ); - }); - - it("emits the fallback when a non-final suppression precedes a final failure", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - await plan.delivery.onDelivered?.( - { text: "cancelled tool reply" }, - { kind: "tool" }, - { - visibleReplySent: false, - suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, - }, - ); - plan.delivery.onError?.(new Error("Telegram final delivery failed"), { - kind: "final", - }); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); - expect(deliveryMocks.deliverReplies).toHaveBeenCalledWith( - expect.objectContaining({ - replies: [{ text: "No response generated. Please try again." }], - }), - ); - }); - - it("emits the fallback when a suppressed block reply precedes a final failure", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - await plan.delivery.onDelivered?.( - { text: "cancelled block reply" }, - { kind: "block" }, - { - visibleReplySent: false, - suppression: { reason: "empty_after_reply_payload_sending_hook" }, - }, - ); - plan.delivery.onError?.(new Error("Telegram final delivery failed"), { - kind: "final", - }); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); - }); - - it("emits the fallback when a final failure precedes a later suppressed final", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - plan.delivery.onError?.(new Error("Telegram final delivery failed"), { - kind: "final", - }); - await plan.delivery.onDelivered?.( - { text: "cancelled final reply" }, - { kind: "final" }, - { - visibleReplySent: false, - suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, - }, - ); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); - }); - - it("preserves a suppressed final after a non-final delivery failure", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - plan.delivery.onError?.(new Error("Telegram tool delivery failed"), { - kind: "tool", - }); - await plan.delivery.onDelivered?.( - { text: "cancelled final reply" }, - { kind: "final" }, - { - visibleReplySent: false, - suppression: { reason: "cancelled_by_reply_payload_sending_hook" }, - }, - ); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); - }); - - it("does not emit the fallback after a partially delivered final", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - plan.delivery.onError?.( - createChannelPartialDeliveryError(new Error("Telegram final delivery failed"), { - visibleReplySent: true, - }), - { kind: "final" }, - ); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).not.toHaveBeenCalled(); - }); - - it("retains the empty fallback for a true non-silent metadata-only native reply", async () => { - dispatchChannelInboundTurnMock.mockImplementationOnce(async (plan) => { - plan.dispatcherOptions?.onSkip?.({}, { kind: "final", reason: "empty" }); - return { - admission: { kind: "dispatch" }, - dispatched: true, - ctxPayload: plan.ctxPayload, - routeSessionKey: plan.route.sessionKey, - dispatchResult: { - queuedFinal: false, - counts: { block: 0, final: 0, tool: 0 }, - }, - }; - }); - const { handler } = registerAndResolveStatusHandler({ cfg: {} }); - - await handler(createTelegramPrivateCommandContext()); - - expect(deliveryMocks.deliverReplies).toHaveBeenCalledOnce(); - expect(deliveryMocks.deliverReplies).toHaveBeenCalledWith( - expect.objectContaining({ - replies: [{ text: "No response generated. Please try again." }], - }), - ); - }); - - it("sends native command error replies silently when silentErrorReplies is enabled", async () => { - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce( - async ({ dispatcherOptions }: DispatchReplyWithBufferedBlockDispatcherParams) => { - await dispatcherOptions.deliver({ text: "oops", isError: true }, { kind: "final" }); - return dispatchReplyResult; - }, - ); - - const { handler } = registerAndResolveStatusHandler({ - cfg: { - channels: { - telegram: { - silentErrorReplies: true, - }, - }, - }, - telegramCfg: { silentErrorReplies: true }, - }); - await handler(createTelegramPrivateCommandContext()); - - const deliveredCall = firstMockArg(deliveryMocks.deliverReplies, "deliverReplies") as - | DeliverRepliesParams - | undefined; - const deliveryParams = requireValue(deliveredCall, "silent error delivery params"); - expect(deliveryParams.silent).toBe(true); - expect(deliveryParams.replies).toHaveLength(1); - expect(deliveryParams.replies[0]?.isError).toBe(true); - }); - - it("routes Telegram native commands through configured ACP topic bindings", async () => { - const boundSessionKey = "agent:codex:acp:binding:telegram:default:feedface"; - persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => - createConfiguredBindingRoute( - { - ...route, - sessionKey: boundSessionKey, - agentId: "codex", - matchedBy: "binding.channel", - }, - createConfiguredAcpTopicBinding(boundSessionKey), - ), - ); - persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ ok: true }); - - const { handler } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: ["200"], - groupAllowFrom: ["200"], - }); - await handler(createTelegramTopicCommandContext()); - - expect(persistentBindingMocks.resolveConfiguredBindingRoute).toHaveBeenCalledTimes(1); - expect(persistentBindingMocks.ensureConfiguredBindingRouteReady).toHaveBeenCalledTimes(1); - const dispatchCall = ( - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< - [{ ctx?: { CommandTargetSessionKey?: string } }] - > - )[0]?.[0]; - expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe(boundSessionKey); - const sessionMetaCall = ( - sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< - [{ sessionKey?: string }] - > - )[0]?.[0]; - expect(sessionMetaCall?.sessionKey).toBe(boundSessionKey); - }); - - it("routes Telegram native commands through topic-specific agent sessions", async () => { - const { handler } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: ["200"], - groupAllowFrom: ["200"], - resolveTelegramGroupConfig: () => ({ - groupConfig: { requireMention: false }, - topicConfig: { agentId: "zu" }, - }), - }); - await handler(createTelegramTopicCommandContext()); - - const dispatchCall = ( - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< - [{ ctx?: { CommandTargetSessionKey?: string } }] - > - )[0]?.[0]; - expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe( - "agent:zu:telegram:group:-1001234567890:topic:42", - ); - const sessionMetaCall = ( - sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< - [{ sessionKey?: string; ctx?: { From?: string; ChatType?: string } }] - > - )[0]?.[0]; - expect(sessionMetaCall?.sessionKey).toBe("agent:zu:telegram:group:-1001234567890:topic:42"); - expect(sessionMetaCall?.ctx?.From).toBe("telegram:group:-1001234567890:topic:42"); - expect(sessionMetaCall?.ctx?.ChatType).toBe("group"); - }); - - it("does not mark paired Telegram DM allowlist entries as native group command owners", async () => { - const { handler, sendMessage } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: [], - groupAllowFrom: [], - storeAllowFrom: ["200"], - }); - await handler(createTelegramTopicCommandContext()); - - expectUnauthorizedNewCommandBlocked(sendMessage); - }); - - it("authorizes paired Telegram DMs without marking them as owners", async () => { - const { handler } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: [], - groupAllowFrom: [], - storeAllowFrom: ["200"], - }); - await handler(createTelegramPrivateCommandContext()); - - const dispatchCall = ( - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< - [ - { - ctx?: { - CommandAuthorized?: boolean; - }; - }, - ] - > - )[0]?.[0]; - expect(dispatchCall?.ctx?.CommandAuthorized).toBe(true); - expect(dispatchCall?.ctx).not.toHaveProperty("OwnerAllowFrom"); - }); - - it("routes Telegram native commands through bound topic sessions", async () => { - sessionBindingMocks.resolveByConversation.mockReturnValue({ - bindingId: "default:-1001234567890:topic:42", - targetSessionKey: "agent:codex-acp:session-1", - }); - - const { handler } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: ["200"], - groupAllowFrom: ["200"], - }); - await handler(createTelegramTopicCommandContext()); - - expect(sessionBindingMocks.resolveByConversation).toHaveBeenCalledWith({ - channel: "telegram", - accountId: "default", - conversationId: "-1001234567890:topic:42", - }); - const dispatchCall = ( - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< - [{ ctx?: { CommandTargetSessionKey?: string } }] - > - )[0]?.[0]; - expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe("agent:codex-acp:session-1"); - const sessionMetaCall = ( - sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< - [{ sessionKey?: string }] - > - )[0]?.[0]; - expect(sessionMetaCall?.sessionKey).toBe("agent:codex-acp:session-1"); - expect(sessionBindingMocks.touch).toHaveBeenCalledWith( - "default:-1001234567890:topic:42", - undefined, - ); - }); - - it("routes Telegram native commands through bound top-level group sessions", async () => { - sessionBindingMocks.resolveByConversation.mockReturnValue({ - bindingId: "default:-1001234567890", - targetSessionKey: "agent:codex-acp:session-group", - }); - - const { handler } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: ["200"], - groupAllowFrom: ["200"], - }); - await handler(createTelegramGroupCommandContext()); - - expect(sessionBindingMocks.resolveByConversation).toHaveBeenCalledWith({ - channel: "telegram", - accountId: "default", - conversationId: "-1001234567890", - }); - const dispatchCall = ( - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< - [{ ctx?: { CommandTargetSessionKey?: string; OriginatingTo?: string } }] - > - )[0]?.[0]; - expect(dispatchCall?.ctx?.CommandTargetSessionKey).toBe("agent:codex-acp:session-group"); - expect(dispatchCall?.ctx?.OriginatingTo).toBe("telegram:-1001234567890"); - const sessionMetaCall = ( - sessionMocks.recordSessionMetaFromInbound.mock.calls as unknown as Array< - [{ sessionKey?: string }] - > - )[0]?.[0]; - expect(sessionMetaCall?.sessionKey).toBe("agent:codex-acp:session-group"); - expect(sessionBindingMocks.touch).toHaveBeenCalledWith("default:-1001234567890", undefined); - }); - - it.each(["new", "reset"] as const)( - "preserves the topic-qualified origin target for native /%s in forum topics", - async (commandName) => { - const { handler } = registerAndResolveCommandHandler({ - commandName, - cfg: {}, - allowFrom: ["200"], - groupAllowFrom: ["200"], - }); - await handler(createTelegramTopicCommandContext()); - - const dispatchCall = ( - replyMocks.dispatchReplyWithBufferedBlockDispatcher.mock.calls as unknown as Array< - [ - { - ctx?: { - CommandTargetSessionKey?: string; - MessageThreadId?: number; - OriginatingTo?: string; - }; - }, - ] - > - )[0]?.[0]; - expectRecordFields( - dispatchCall?.ctx, - { - CommandTargetSessionKey: "agent:main:telegram:group:-1001234567890:topic:42", - MessageThreadId: 42, - OriginatingTo: "telegram:-1001234567890:topic:42", - }, - "topic dispatch context", - ); - }, - ); - - it("aborts native command dispatch when configured ACP topic binding cannot initialize", async () => { - const boundSessionKey = "agent:codex:acp:binding:telegram:default:feedface"; - persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => - createConfiguredBindingRoute( - { - ...route, - sessionKey: boundSessionKey, - agentId: "codex", - matchedBy: "binding.channel", - }, - createConfiguredAcpTopicBinding(boundSessionKey), - ), - ); - persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ - ok: false, - error: "gateway unavailable", - }); - - const { handler, sendMessage } = registerAndResolveStatusHandler({ - cfg: {}, - allowFrom: ["200"], - groupAllowFrom: ["200"], - }); - await handler(createTelegramTopicCommandContext()); - - expect(replyMocks.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled(); - expectSendMessageCall({ - sendMessage, - chatId: -1001234567890, - text: "Configured ACP binding is unavailable right now. Please try again.", - optionFields: { message_thread_id: 42 }, - label: "unavailable ACP binding", - }); - }); - - it("keeps /new blocked in ACP-bound Telegram topics when sender is unauthorized", async () => { - const boundSessionKey = "agent:codex:acp:binding:telegram:default:feedface"; - persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => - createConfiguredBindingRoute( - { - ...route, - sessionKey: boundSessionKey, - agentId: "codex", - matchedBy: "binding.channel", - }, - createConfiguredAcpTopicBinding(boundSessionKey), - ), - ); - persistentBindingMocks.ensureConfiguredBindingRouteReady.mockResolvedValue({ ok: true }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "new", - cfg: {}, - allowFrom: [], - groupAllowFrom: [], - }); - await handler(createTelegramTopicCommandContext()); - - expectUnauthorizedNewCommandBlocked(sendMessage); - }); - - it("keeps /new blocked for unbound Telegram topics when sender is unauthorized", async () => { - persistentBindingMocks.resolveConfiguredBindingRoute.mockImplementation(({ route }) => - createConfiguredBindingRoute(route, null), - ); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "new", - cfg: {}, - allowFrom: [], - groupAllowFrom: [], - }); - await handler(createTelegramTopicCommandContext()); - - expectUnauthorizedNewCommandBlocked(sendMessage); - }); - - it("passes persisted topic session identity to plugin commands", async () => { - sessionMocks.resolveStorePath.mockReturnValue("/tmp/openclaw-sessions/sessions.json"); - sessionMocks.getSessionEntry.mockReturnValue({ - authProfileOverride: "openai:owner@example.com", - sessionId: "sess-topic", - updatedAt: 1, - }); - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:telegram:group:-1001234567890:topic:42": { - authProfileOverride: "openai:owner@example.com", - sessionId: "sess-topic", - updatedAt: 1, - }, - }); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "plugin_meta", - cfg: { commands: { allowFrom: { telegram: ["200"] } } } as OpenClawConfig, - groupAllowFrom: ["-1001234567890"], - pluginCommandSpecs: [ - { - name: "plugin_meta", - description: "Codex", - acceptsArgs: true, - }, - ] as TelegramPluginCommandSpecs, - }); - await handler( - createTelegramTopicCommandContext({ match: "bind --cwd /tmp/work", threadId: 42 }), - ); - - expectRecordFields( - (pluginRuntimeMocks.executePluginCommand.mock.calls as unknown as Array<[unknown]>)[0]?.[0], - { - sessionKey: "agent:main:telegram:group:-1001234567890:topic:42", - sessionId: "sess-topic", - messageThreadId: 42, - }, - "plugin command params", - ); - }); - - it("moves the target session to the profile returned by Telegram /login codex", async () => { - const finishLogin = createDeferred(); - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - authProfileOverride: "openai:owner@example.com", - sessionId: "sess-main", - updatedAt: 1, - }, - }); - const runModelsAuthLoginFlow = vi.fn(async (opts) => { - await opts.prompter.deviceCode?.({ - title: "OpenAI Codex device code", - code: "ABCD-EFGH", - expiresInMinutes: 15, - message: "URL: https://auth.openai.com/codex/device", - }); - await finishLogin.promise; - return { - providerId: "openai", - methodId: "device-code", - profiles: [ - { profileId: "openai:new-owner@example.com", provider: "openai", mode: "oauth" }, - ], - }; - }); - - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - expect(sessionMocks.updateSessionStoreEntry).not.toHaveBeenCalled(); - finishLogin.resolve(); - - expect(runModelsAuthLoginFlow).toHaveBeenCalledWith( - expect.objectContaining({ - provider: "openai", - method: "device-code", - agent: "main", - }), - ); - expect( - (runModelsAuthLoginFlow.mock.calls[0]?.[0] as { profileId?: string } | undefined)?.profileId, - ).toBeUndefined(); - await vi.waitFor(() => - expect(sessionMocks.updateSessionStoreEntry).toHaveBeenCalledWith({ - sessionKey: "agent:main:main", - storePath: "/tmp/openclaw-sessions.json", - requireWriteSuccess: true, - skipMaintenance: true, - update: expect.any(Function), - }), - ); - const patchUpdate = ( - sessionMocks.updateSessionStoreEntry.mock.calls[0]?.[0] as { - update?: (entry: Record) => Record; - } - )?.update?.({ - authProfileOverride: "openai:owner@example.com", - sessionId: "sess-main", - updatedAt: 1, - }); - expect(patchUpdate).toEqual({ - authProfileOverride: "openai:new-owner@example.com", - authProfileOverrideSource: "user", - authProfileOverrideCompactionCount: undefined, - }); - await vi.waitFor(() => - expect(sendMessage).toHaveBeenCalledWith( - 100, - "Codex login complete. Try your request again now.", - {}, - ), - ); - }); - - it("moves a session created while Telegram login is pending to the returned profile", async () => { - const finishLogin = createDeferred(); - let sessionStore: Record = {}; - sessionMocks.loadSessionStore.mockImplementation(() => sessionStore); - const runModelsAuthLoginFlow = vi.fn(async (opts) => { - await opts.prompter.deviceCode?.({ - title: "OpenAI Codex device code", - code: "NEW-SESSION", - }); - await finishLogin.promise; - return { - providerId: "openai", - methodId: "device-code", - profiles: [ - { profileId: "openai:new-owner@example.com", provider: "openai", mode: "oauth" }, - ], - }; - }); - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - sessionStore = { - "agent:main:main": { - sessionId: "sess-created-during-login", - updatedAt: 2, - }, - }; - finishLogin.resolve(); - - await vi.waitFor(() => expect(sessionMocks.updateSessionStoreEntry).toHaveBeenCalledTimes(1)); - const update = ( - sessionMocks.updateSessionStoreEntry.mock.calls[0]?.[0] as { - update?: (entry: SessionEntry) => Partial | null; - } - )?.update; - expect( - update?.({ - sessionId: "sess-created-during-login", - updatedAt: 2, - }), - ).toEqual({ - authProfileOverride: "openai:new-owner@example.com", - authProfileOverrideSource: "user", - authProfileOverrideCompactionCount: undefined, - }); - await vi.waitFor(() => - expect(sendMessage).toHaveBeenCalledWith( - 100, - "Codex login complete. Try your request again now.", - {}, - ), - ); - }); - - it("preserves a later user-selected profile on a session created during Telegram login", async () => { - const finishLogin = createDeferred(); - let sessionStore: Record = {}; - sessionMocks.loadSessionStore.mockImplementation(() => sessionStore); - const runModelsAuthLoginFlow = vi.fn(async (opts) => { - await opts.prompter.deviceCode?.({ - title: "OpenAI Codex device code", - code: "LATER-USER-SELECTION", - }); - await finishLogin.promise; - return { - providerId: "openai", - methodId: "device-code", - profiles: [{ profileId: "openai:login-profile", provider: "openai", mode: "oauth" }], - }; - }); - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - sessionStore = { - "agent:main:main": { - authProfileOverride: "openai:later-user-profile", - authProfileOverrideSource: "user", - sessionId: "sess-created-during-login", - updatedAt: 2, - }, - }; - finishLogin.resolve(); - - await vi.waitFor(() => - expect(sendMessage).toHaveBeenCalledWith( - 100, - "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", - {}, - ), - ); - expect(sessionStore["agent:main:main"]?.authProfileOverride).toBe("openai:later-user-profile"); - expect(sendMessage).not.toHaveBeenCalledWith( - 100, - "Codex login complete. Try your request again now.", - expect.any(Object), - ); - }); - - it("marks a same-profile Telegram login as user-selected", async () => { - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - authProfileOverride: "openai:owner@example.com", - authProfileOverrideSource: "auto", - authProfileOverrideCompactionCount: 2, - sessionId: "sess-main", - updatedAt: 1, - }, - }); - const runModelsAuthLoginFlow = vi.fn(async () => ({ - providerId: "openai", - methodId: "device-code", - profiles: [{ profileId: "openai:owner@example.com", provider: "openai", mode: "oauth" }], - })); - const { handler } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - - const update = ( - sessionMocks.updateSessionStoreEntry.mock.calls[0]?.[0] as { - update?: (entry: Record) => Record; - } - )?.update; - expect(update).toBeTypeOf("function"); - expect( - update?.({ - authProfileOverride: "openai:owner@example.com", - authProfileOverrideSource: "auto", - authProfileOverrideCompactionCount: 2, - sessionId: "sess-main", - updatedAt: 1, - }), - ).toEqual({ - authProfileOverride: "openai:owner@example.com", - authProfileOverrideSource: "user", - authProfileOverrideCompactionCount: undefined, - }); - expect( - update?.({ - authProfileOverride: "openai:owner@example.com", - authProfileOverrideSource: "user", - sessionId: "sess-main", - updatedAt: 2, - }), - ).toBeNull(); - }); - - it("reports partial success when Telegram cannot persist the returned profile", async () => { - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": { - authProfileOverride: "openai:old-owner@example.com", - sessionId: "sess-main", - updatedAt: 1, - }, - }); - sessionMocks.updateSessionStoreEntry.mockRejectedValueOnce(new Error("write failed")); - const runModelsAuthLoginFlow = vi.fn(async () => ({ - providerId: "openai", - methodId: "device-code", - profiles: [{ profileId: "openai:new-owner@example.com", provider: "openai", mode: "oauth" }], - })); - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - - expect(sendMessage).toHaveBeenCalledWith( - 100, - "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", - {}, - ); - expect(sendMessage).not.toHaveBeenCalledWith( - 100, - "Codex login complete. Try your request again now.", - expect.any(Object), - ); - }); - - it("reports partial success when Telegram login returns no OpenAI profile", async () => { - const runModelsAuthLoginFlow = vi.fn(async () => ({ - providerId: "openai", - methodId: "device-code", - profiles: [], - })); - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - - expect(sendMessage).toHaveBeenCalledWith( - 100, - "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", - {}, - ); - expect(sendMessage).not.toHaveBeenCalledWith( - 100, - "Codex login complete. Try your request again now.", - expect.any(Object), - ); - }); - - it("revalidates an unchanged Telegram profile after device login", async () => { - const previousEntry = { - authProfileOverride: "openai:owner@example.com", - authProfileOverrideSource: "user", - sessionId: "sess-main", - updatedAt: 1, - }; - sessionMocks.loadSessionStore.mockReturnValue({ - "agent:main:main": previousEntry, - }); - sessionMocks.updateSessionStoreEntry.mockImplementationOnce(async (params) => { - const concurrentEntry = { - ...previousEntry, - authProfileOverride: "openai:concurrent-owner@example.com", - updatedAt: 2, - }; - const patch = await params.update({ ...concurrentEntry }); - return patch ? { ...concurrentEntry, ...patch } : concurrentEntry; - }); - const runModelsAuthLoginFlow = vi.fn(async () => ({ - providerId: "openai", - methodId: "device-code", - profiles: [{ profileId: "openai:owner@example.com", provider: "openai", mode: "oauth" }], - })); - const { handler, sendMessage } = registerAndResolveCommandHandler({ - commandName: "login", - cfg: { - commands: { native: true, ownerAllowFrom: ["200"] }, - } as OpenClawConfig, - allowFrom: ["200"], - runModelsAuthLoginFlow, - }); - - await handler(createTelegramPrivateCommandContext({ match: "codex", userId: 200 })); - - expect(sendMessage).toHaveBeenCalledWith( - 100, - "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually.", - {}, - ); - expect(sendMessage).not.toHaveBeenCalledWith( - 100, - "Codex login complete. Try your request again now.", - expect.any(Object), - ); - }); - - it("passes session identity to plugin commands when the entry has no file", async () => { - sessionMocks.resolveStorePath.mockReturnValue("/tmp/openclaw-sessions/sessions.json"); - sessionMocks.getSessionEntry.mockReturnValue({ - sessionId: "sess-main", - updatedAt: 1, - }); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "plugin_meta", - cfg: { commands: { allowFrom: { telegram: ["200"] } } } as OpenClawConfig, - pluginCommandSpecs: [ - { - name: "plugin_meta", - description: "Codex", - acceptsArgs: true, - }, - ] as TelegramPluginCommandSpecs, - }); - await handler(createTelegramPrivateCommandContext({ match: "status" })); - - expectRecordFields( - (pluginRuntimeMocks.executePluginCommand.mock.calls as unknown as Array<[unknown]>)[0]?.[0], - { - sessionKey: "agent:main:main", - sessionId: "sess-main", - sessionFile: "sqlite:main:sess-main:/tmp/openclaw-sessions/sessions.json", - }, - "plugin command params", - ); - }); - - it("passes SQLite transcript markers to plugin commands without path resolution", async () => { - const storePath = "/tmp/openclaw-sessions/sessions.json"; - const marker = `sqlite:main:sess-main:${storePath}`; - sessionMocks.resolveStorePath.mockReturnValue(storePath); - sessionMocks.getSessionEntry.mockReturnValue({ - sessionId: "sess-main", - sessionFile: marker, - updatedAt: 1, - }); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "plugin_meta", - cfg: { commands: { allowFrom: { telegram: ["200"] } } } as OpenClawConfig, - pluginCommandSpecs: [ - { - name: "plugin_meta", - description: "Codex", - acceptsArgs: true, - }, - ] as TelegramPluginCommandSpecs, - }); - await handler(createTelegramPrivateCommandContext({ match: "status" })); - - expectRecordFields( - (pluginRuntimeMocks.executePluginCommand.mock.calls as unknown as Array<[unknown]>)[0]?.[0], - { - sessionKey: "agent:main:main", - sessionId: "sess-main", - sessionFile: marker, - }, - "plugin command params", - ); - }); - - it("replaces stale legacy transcript paths for plugin commands", async () => { - const storePath = "/tmp/openclaw-sessions/sessions.json"; - const marker = `sqlite:main:sess-main:${storePath}`; - sessionMocks.resolveStorePath.mockReturnValue(storePath); - sessionMocks.getSessionEntry.mockReturnValue({ - sessionId: "sess-main", - sessionFile: "sess-main.jsonl", - updatedAt: 1, - }); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "plugin_meta", - cfg: { commands: { allowFrom: { telegram: ["200"] } } } as OpenClawConfig, - pluginCommandSpecs: [ - { - name: "plugin_meta", - description: "Codex", - acceptsArgs: true, - }, - ] as TelegramPluginCommandSpecs, - }); - await handler(createTelegramPrivateCommandContext({ match: "status" })); - - expectRecordFields( - (pluginRuntimeMocks.executePluginCommand.mock.calls as unknown as Array<[unknown]>)[0]?.[0], - { - sessionKey: "agent:main:main", - sessionId: "sess-main", - sessionFile: marker, - }, - "plugin command params", - ); - }); - - it("sends an empty-response fallback when a plugin command returns undefined", async () => { - pluginRuntimeMocks.executePluginCommand.mockResolvedValue(undefined as never); - - const { handler } = registerAndResolveCommandHandler({ - commandName: "plugin_meta", - cfg: { commands: { allowFrom: { telegram: ["200"] } } } as OpenClawConfig, - pluginCommandSpecs: [ - { - name: "plugin_meta", - description: "Codex", - acceptsArgs: true, - }, - ] as TelegramPluginCommandSpecs, - }); - await handler(createTelegramPrivateCommandContext({ match: "status" })); - - const deliveryCall = requireValue( - firstMockArg(deliveryMocks.deliverReplies, "deliverReplies") as - | DeliverRepliesParams - | undefined, - "empty response delivery params", - ); - expect(deliveryCall.replies).toEqual([{ text: "No response generated. Please try again." }]); - }); -}); -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/extensions/telegram/src/bot-native-commands.test.ts b/extensions/telegram/src/bot-native-commands.test.ts index 89bd3d06ce28..09e997f3331e 100644 --- a/extensions/telegram/src/bot-native-commands.test.ts +++ b/extensions/telegram/src/bot-native-commands.test.ts @@ -13,9 +13,6 @@ import { createCommandBot, createNativeCommandTestParams, createPrivateCommandContext, - deliverReplies, - editMessageTelegram, - emitTelegramMessageSentHooks, listSkillCommandsForAgents, resetNativeCommandMenuMocks, waitForRegisteredCommands, @@ -23,19 +20,9 @@ import { import { resetTelegramForumFlagCacheForTest } from "./bot/helpers.js"; import { normalizeTelegramCommandName, TELEGRAM_COMMAND_NAME_PATTERN } from "./command-config.js"; -type CommandBotHarness = ReturnType; type TelegramInlineKeyboardReplyMarkup = { inline_keyboard?: Array>; }; -type PlugCommandHarnessParams = { - botHarness?: CommandBotHarness; - cfg?: OpenClawConfig; - command?: Record; - acceptsArgs?: boolean; - args?: string; - result?: Record; - registerOverrides?: Partial[0]>; -}; const pluginCommandHandler = vi.fn(async (_ctx: Record) => ({ text: "ok" })); @@ -62,35 +49,6 @@ function registerTestPluginCommand(params: { ).toEqual({ ok: true }); } -function primePlugCommand(params: PlugCommandHarnessParams = {}) { - registerTestPluginCommand({ - name: "plug", - description: "Plugin command", - acceptsArgs: params.acceptsArgs ?? true, - command: params.command, - result: params.result, - }); -} - -function registerPlugCommand(params: PlugCommandHarnessParams = {}) { - const botHarness = params.botHarness ?? createCommandBot(); - primePlugCommand(params); - registerTelegramNativeCommands({ - ...createNativeCommandTestParams(params.cfg ?? {}, { - bot: botHarness.bot, - }), - ...params.registerOverrides, - }); - const handler = botHarness.commandHandlers.get("plug"); - if (!handler) { - throw new Error("expected plug command handler to be registered"); - } - return { - ...botHarness, - handler, - }; -} - function collectCallbackData(replyMarkup: TelegramInlineKeyboardReplyMarkup | undefined): string[] { const callbackData: string[] = []; for (const row of replyMarkup?.inline_keyboard ?? []) { @@ -111,39 +69,9 @@ function firstCall(mock: { mock: { calls: Array> } }) { return call; } -function firstCallArg(mock: { mock: { calls: Array> } }, argIndex = 0) { - const arg = firstCall(mock)[argIndex]; - if (!arg || typeof arg !== "object") { - throw new Error(`expected first mock call arg ${argIndex}`); - } - return arg as Record; -} - -function firstDeliverRepliesParams() { - return firstCallArg(deliverReplies as unknown as { mock: { calls: Array> } }); -} - -function firstExecutePluginCommandParams() { - return firstCallArg( - pluginCommandHandler as unknown as { - mock: { calls: Array> }; - }, - ); -} - -function replyAt(params: Record, index = 0) { - const replies = params.replies as Array> | undefined; - const reply = replies?.[index]; - if (!reply) { - throw new Error(`expected reply ${index}`); - } - return reply; -} - resetPluginRuntimeStateForTest(); setActivePluginRegistry(createEmptyPluginRegistry()); -const { registerTelegramNativeCommands, parseTelegramNativeCommandCallbackData } = - await import("./bot-native-commands.js"); +const { registerTelegramNativeCommands } = await import("./bot-native-commands.js"); registerTelegramNativeCommands(createNativeCommandTestParams({})); describe("registerTelegramNativeCommands", () => { @@ -439,476 +367,5 @@ describe("registerTelegramNativeCommands", () => { "tgcmd:/fast status", ]); expect(labels).toEqual(["on", "off", "auto (30 sec)", "default", "status"]); - expect(parseTelegramNativeCommandCallbackData("tgcmd:/fast status")).toBe("/fast status"); - expect(parseTelegramNativeCommandCallbackData("tgcmd:/fast auto")).toBe("/fast auto"); - expect(parseTelegramNativeCommandCallbackData("tgcmd:/fast default")).toBe("/fast default"); - expect(parseTelegramNativeCommandCallbackData("tgcmd:fast status")).toBeNull(); - }); - - it("passes agent-scoped media roots for plugin command replies with media", async () => { - const mediaMaxBytes = 50 * 1024 * 1024; - const cfg: OpenClawConfig = { - agents: { - list: [{ id: "main", default: true }, { id: "work" }], - }, - bindings: [{ agentId: "work", match: { channel: "telegram", accountId: "default" } }], - }; - - const { handler, sendMessage } = registerPlugCommand({ - cfg, - result: { - text: "with media", - mediaUrl: "/tmp/workspace-work/render.png", - }, - registerOverrides: { - mediaMaxBytes, - } as Partial[0]>, - }); - - await handler(createPrivateCommandContext()); - - const deliverParams = firstDeliverRepliesParams(); - expect(deliverParams.mediaMaxBytes).toBe(mediaMaxBytes); - const mediaLocalRoots = deliverParams.mediaLocalRoots as Array | undefined; - expect(mediaLocalRoots?.some((root) => /[\\/]\.openclaw[\\/]workspace-work$/.test(root))).toBe( - true, - ); - expect(sendMessage).not.toHaveBeenCalledWith(123, "Command not found."); - }); - - it("delivers presentation-only tables returned by plugin commands", async () => { - const presentation = { - title: "FY25 outlook", - blocks: [ - { - type: "table", - caption: "Pipeline", - headers: ["Account", "Stage"], - rows: [["Acme", "Won"]], - }, - ], - }; - const { handler } = registerPlugCommand({ result: { presentation } }); - - await handler(createPrivateCommandContext()); - - expect(replyAt(firstDeliverRepliesParams())).toMatchObject({ presentation }); - expect(replyAt(firstDeliverRepliesParams()).text).toBeUndefined(); - }); - - it("delivers Telegram button-only plugin command replies", async () => { - const buttons = [[{ text: "Retry", callback_data: "retry" }]]; - const { handler } = registerPlugCommand({ - result: { channelData: { telegram: { buttons } } }, - }); - - await handler(createPrivateCommandContext()); - - expect(replyAt(firstDeliverRepliesParams())).toEqual({ - channelData: { telegram: { buttons } }, - }); - }); - - it("targets reaction-only plugin replies at the invoking command message", async () => { - const { handler } = registerPlugCommand({ - result: { channelData: { telegram: { reaction: { emoji: "🔥" } } } }, - }); - - await handler(createPrivateCommandContext({ messageId: 321 })); - - const deliveryParams = firstDeliverRepliesParams(); - expect(replyAt(deliveryParams)).toEqual({ - replyToId: "321", - channelData: { telegram: { reaction: { emoji: "🔥" } } }, - }); - expect(deliveryParams.replyToMode).toBe("all"); - }); - - it("uses the empty-response fallback for unrelated metadata-only plugin results", async () => { - const { handler } = registerPlugCommand({ - result: { channelData: { plugin: { traceId: "trace-1" } } }, - }); - - await handler(createPrivateCommandContext()); - - expect(replyAt(firstDeliverRepliesParams())).toEqual({ - text: "No response generated. Please try again.", - }); - }); - - it("replies to unmatched plugin commands in the originating forum topic", async () => { - const { handler, sendMessage } = registerPlugCommand({ acceptsArgs: false }); - - await handler({ - match: "unexpected", - message: { - message_id: 2, - date: Math.floor(Date.now() / 1000), - chat: { - id: -1001234567890, - type: "supergroup", - title: "Forum Group", - is_forum: true, - }, - message_thread_id: 77, - from: { id: 200, username: "bob" }, - }, - }); - - const sendMessageCall = firstCall(sendMessage); - expect(sendMessageCall[0]).toBe(-1001234567890); - expect(sendMessageCall[1]).toBe("Command not found."); - expect( - (sendMessageCall[2] as { message_thread_id?: number } | undefined)?.message_thread_id, - ).toBe(77); - }); - - it("uses plugin command metadata to send and edit a Telegram progress placeholder", async () => { - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { - telegram: - "Running this command now...\n\nI'll edit this message with the final result when it's ready.", - }, - }, - result: { - text: "Command completed successfully", - }, - }); - - await handler( - createPrivateCommandContext({ - match: "now", - }), - ); - - const sendMessageCall = firstCall(sendMessage); - expect(sendMessageCall[0]).toBe(100); - expect(String(sendMessageCall[1])).toContain("Running this command now"); - expect(sendMessageCall[2]).toBeUndefined(); - const editCall = firstCall( - editMessageTelegram as unknown as { mock: { calls: Array> } }, - ); - expect(editCall[0]).toBe(100); - expect(editCall[1]).toBe(999); - expect(String(editCall[2])).toContain("Command completed successfully"); - expect((editCall[3] as { accountId?: string } | undefined)?.accountId).toBe("default"); - expect(deleteMessage).not.toHaveBeenCalled(); - expect(deliverReplies).not.toHaveBeenCalled(); - const hookParams = firstCallArg( - emitTelegramMessageSentHooks as unknown as { mock: { calls: Array> } }, - ); - expect(hookParams.chatId).toBe("100"); - expect(hookParams.content).toBe("Command completed successfully"); - expect(hookParams.messageId).toBe(999); - expect(hookParams.success).toBe(true); - }); - - it("preserves Telegram buttons when editing a metadata-driven progress placeholder", async () => { - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { telegram: "Working on it..." }, - }, - result: { - text: "Choose an option", - channelData: { - telegram: { - buttons: [[{ text: "Approve", callback_data: "approve" }]], - }, - }, - }, - }); - - await handler(createPrivateCommandContext({ match: "now" })); - - expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); - const editCall = firstCall( - editMessageTelegram as unknown as { mock: { calls: Array> } }, - ); - expect(editCall[0]).toBe(100); - expect(editCall[1]).toBe(999); - expect(editCall[2]).toBe("Choose an option"); - expect((editCall[3] as { buttons?: unknown } | undefined)?.buttons).toEqual([ - [{ text: "Approve", callback_data: "approve" }], - ]); - expect(deleteMessage).not.toHaveBeenCalled(); - expect(deliverReplies).not.toHaveBeenCalled(); - }); - - it("delivers reactions after cleaning up a metadata-driven progress placeholder", async () => { - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { telegram: "Working on it..." }, - }, - result: { - text: "Command completed successfully", - channelData: { telegram: { reaction: { emoji: "🔥" } } }, - }, - }); - - await handler(createPrivateCommandContext({ match: "now", messageId: 321 })); - - expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); - expect(editMessageTelegram).not.toHaveBeenCalled(); - expect(deleteMessage).toHaveBeenCalledWith(100, 999); - const deliveryParams = firstDeliverRepliesParams(); - expect(deliveryParams.replyToMode).toBe("all"); - expect(replyAt(deliveryParams)).toEqual({ - text: "Command completed successfully", - replyToId: "321", - channelData: { telegram: { reaction: { emoji: "🔥" } } }, - }); - }); - - it("falls back to a normal reply when a metadata-driven progress result is not editable", async () => { - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { telegram: "Working on it..." }, - }, - result: { - text: "rich output", - mediaUrl: "/tmp/render.png", - }, - }); - - await handler( - createPrivateCommandContext({ - match: "now", - }), - ); - - expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); - expect(editMessageTelegram).not.toHaveBeenCalled(); - expect(deleteMessage).toHaveBeenCalledWith(100, 999); - expect(replyAt(firstDeliverRepliesParams()).mediaUrl).toBe("/tmp/render.png"); - }); - - it("falls back to a normal reply when a progress result has presentation controls", async () => { - const presentation = { - blocks: [ - { - type: "buttons", - buttons: [{ label: "Approve", action: { type: "callback", value: "/approve yes" } }], - }, - ], - }; - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { telegram: "Working on it..." }, - }, - result: { - text: "Approval required", - presentation, - }, - }); - - await handler(createPrivateCommandContext({ match: "now" })); - - expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); - expect(editMessageTelegram).not.toHaveBeenCalled(); - expect(deleteMessage).toHaveBeenCalledWith(100, 999); - expect(replyAt(firstDeliverRepliesParams())).toMatchObject({ - text: "Approval required", - presentation, - }); - }); - - it("cleans up the progress placeholder before falling back after an edit failure", async () => { - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { telegram: "Working on it..." }, - }, - result: { - text: "Command completed successfully", - }, - }); - editMessageTelegram.mockRejectedValueOnce(new Error("message to edit not found")); - - await handler(createPrivateCommandContext({ match: "now" })); - - expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); - expect(editMessageTelegram).toHaveBeenCalledTimes(1); - expect(deleteMessage).toHaveBeenCalledWith(100, 999); - expect(replyAt(firstDeliverRepliesParams()).text).toBe("Command completed successfully"); - }); - - it("cleans up the progress placeholder when Telegram suppresses a local exec approval reply", async () => { - const { handler, sendMessage, deleteMessage } = registerPlugCommand({ - args: "now", - command: { - nativeProgressMessages: { telegram: "Working on it..." }, - }, - result: { - text: "Approval required.\n\n```txt\n/approve 7f423fdc allow-once\n```", - channelData: { - execApproval: { - approvalId: "7f423fdc-1111-2222-3333-444444444444", - approvalSlug: "7f423fdc", - allowedDecisions: ["allow-once", "allow-always", "deny"], - }, - }, - }, - cfg: { - channels: { - telegram: { - execApprovals: { - enabled: true, - approvers: ["12345"], - target: "dm", - }, - }, - }, - }, - }); - - await handler(createPrivateCommandContext({ match: "now" })); - - expect(sendMessage).toHaveBeenCalledWith(100, "Working on it...", undefined); - expect(deleteMessage).toHaveBeenCalledWith(100, 999); - expect(editMessageTelegram).not.toHaveBeenCalled(); - expect(deliverReplies).not.toHaveBeenCalled(); - }); - - it("sends plugin command error replies silently when silentErrorReplies is enabled", async () => { - const { handler } = registerPlugCommand({ - cfg: { - channels: { - telegram: { - silentErrorReplies: true, - }, - }, - }, - result: { - text: "plugin failed", - isError: true, - }, - registerOverrides: { - telegramCfg: { silentErrorReplies: true } as TelegramAccountConfig, - }, - }); - - await handler(createPrivateCommandContext()); - - const deliverParams = firstDeliverRepliesParams(); - expect(deliverParams.silent).toBe(true); - expect(replyAt(deliverParams).isError).toBe(true); - }); - - it("uses rich messages for plugin command replies when enabled", async () => { - const { handler } = registerPlugCommand({ - cfg: { - channels: { - telegram: { - richMessages: true, - }, - }, - }, - registerOverrides: { - telegramCfg: { richMessages: true } as TelegramAccountConfig, - }, - }); - - await handler(createPrivateCommandContext()); - - expect(firstDeliverRepliesParams().richMessages).toBe(true); - }); - - it("forwards topic-scoped binding context to Telegram plugin commands", async () => { - const { handler } = registerPlugCommand(); - - await handler({ - match: "", - message: { - message_id: 2, - date: Math.floor(Date.now() / 1000), - chat: { - id: -1001234567890, - type: "supergroup", - title: "Forum Group", - is_forum: true, - }, - message_thread_id: 77, - from: { id: 200, username: "bob" }, - }, - }); - - const commandParams = firstExecutePluginCommandParams(); - expect(commandParams.channel).toBe("telegram"); - expect(commandParams.accountId).toBe("default"); - expect(commandParams.from).toBe("telegram:group:-1001234567890:topic:77"); - expect(commandParams.to).toBe("telegram:-1001234567890"); - expect(commandParams.messageThreadId).toBe(77); - }); - - it("treats Telegram forum #General commands as topic 1 when Telegram omits topic metadata", async () => { - const getChat = vi.fn(async () => ({ id: -1001234567890, type: "supergroup", is_forum: true })); - const { handler } = registerPlugCommand({ - botHarness: createCommandBot({ api: { getChat } }), - }); - - await handler({ - match: "", - message: { - message_id: 2, - date: Math.floor(Date.now() / 1000), - chat: { - id: -1001234567890, - type: "supergroup", - title: "Forum Group", - }, - from: { id: 200, username: "bob" }, - }, - }); - - expect(getChat).toHaveBeenCalledWith(-1001234567890); - const commandParams = firstExecutePluginCommandParams(); - expect(commandParams.accountId).toBe("default"); - expect(commandParams.from).toBe("telegram:group:-1001234567890:topic:1"); - expect(commandParams.to).toBe("telegram:-1001234567890"); - expect(commandParams.messageThreadId).toBe(1); - }); - - it("forwards direct-message binding context to Telegram plugin commands", async () => { - const { handler } = registerPlugCommand(); - - await handler(createPrivateCommandContext({ chatId: 100, userId: 200 })); - - const commandParams = firstExecutePluginCommandParams(); - expect(commandParams.channel).toBe("telegram"); - expect(commandParams.accountId).toBe("default"); - expect(commandParams.from).toBe("telegram:100"); - expect(commandParams.to).toBe("telegram:100"); - expect(commandParams.messageThreadId).toBeUndefined(); - }); - - it("suppresses the fallback reply when a plugin command returns suppressReply: true", async () => { - const { handler } = registerPlugCommand({ - result: { suppressReply: true }, - }); - - await handler(createPrivateCommandContext()); - - expect(deliverReplies).not.toHaveBeenCalled(); - expect(editMessageTelegram).not.toHaveBeenCalled(); - }); - - it("uses bot topic capability for Telegram plugin command DM topic session keys", async () => { - const { handler } = registerPlugCommand(); - - await handler({ - ...createPrivateCommandContext({ chatId: 100, userId: 200, threadId: 77 }), - me: { has_topics_enabled: true }, - }); - - const commandParams = firstExecutePluginCommandParams(); - expect(commandParams.sessionKey).toBe("agent:main:main:thread:100:77"); - const deliveryParams = firstDeliverRepliesParams(); - expect(deliveryParams.sessionKeyForInternalHooks).toBe("agent:main:main:thread:100:77"); }); }); diff --git a/extensions/telegram/src/bot-native-commands.ts b/extensions/telegram/src/bot-native-commands.ts index 3f5dbfd7b861..8fbf7df8a7e3 100644 --- a/extensions/telegram/src/bot-native-commands.ts +++ b/extensions/telegram/src/bot-native-commands.ts @@ -1,74 +1,23 @@ -// Telegram plugin module implements bot native commands behavior. -import { randomUUID } from "node:crypto"; +// Telegram plugin module implements native command registration behavior. import type { Bot, Context } from "grammy"; import { - loadPreparedModelCatalog, - resolveAgentConfig, - resolveAgentDir, - resolveDefaultModelForAgent, - resolveThinkingDefaultWithRuntimeCatalog, -} from "openclaw/plugin-sdk/agent-runtime"; -import { - isChannelPartialDeliveryError, - type ChannelInboundTurnPlan, -} from "openclaw/plugin-sdk/channel-inbound"; -import { resolveChannelStreamingBlockEnabled } from "openclaw/plugin-sdk/channel-outbound"; -import { resolveNativeCommandSessionTargets } from "openclaw/plugin-sdk/command-auth-native"; -import { - buildCommandTextFromArgs, findCommandByNativeName, - formatFastModeCurrentStatus, - formatCommandArgMenuTitle, listNativeCommandSpecs, listNativeCommandSpecsForConfig, - parseCommandArgs, - resolveEffectiveAgentRuntime, - resolveCommandArgMenu, - resolveFastModeState, - resolveStoredModelOverride, - type CommandArgs, } from "openclaw/plugin-sdk/command-auth-native"; -import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; -import type { ChannelGroupPolicy } from "openclaw/plugin-sdk/config-contracts"; import type { - ReplyToMode, + ChannelGroupPolicy, + OpenClawConfig, TelegramAccountConfig, - TelegramDirectConfig, - TelegramGroupConfig, - TelegramTopicConfig, } from "openclaw/plugin-sdk/config-contracts"; -import { createDeferred } from "openclaw/plugin-sdk/extension-shared"; import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime"; -import { resolveMarkdownTableMode } from "openclaw/plugin-sdk/markdown-table-runtime"; -import { - createPluginCommandRuntime, - PLUGIN_COMMAND_DISPATCH, - type PluginCommandCatalogDecision, -} from "openclaw/plugin-sdk/plugin-command-runtime"; -import { codexChannelLoginRuntime } from "openclaw/plugin-sdk/provider-auth-login-flow-runtime"; -import { hasOutboundReplyContent } from "openclaw/plugin-sdk/reply-payload"; +import { createPluginCommandRuntime } from "openclaw/plugin-sdk/plugin-command-runtime"; import { resolveAgentRoute } from "openclaw/plugin-sdk/routing"; -import { danger, logVerbose } from "openclaw/plugin-sdk/runtime-env"; -import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env"; -import { - formatSqliteSessionFileMarker, - getSessionEntry, - resolveStorePath, - type SessionEntry, - updateSessionStoreEntry, -} from "openclaw/plugin-sdk/session-store-runtime"; -import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime"; -import { escapeHtml } from "openclaw/plugin-sdk/text-utility-runtime"; -import { expandTelegramAllowFromWithAccessGroups } from "./access-groups.js"; -import { resolveTelegramAccount } from "./accounts.js"; -import { withTelegramApiErrorLogging } from "./api-logging.js"; -import { normalizeDmAllowFromWithStore, resolveTelegramEffectiveDmPolicy } from "./bot-access.js"; -import type { TelegramBotDeps } from "./bot-deps.js"; +import { danger, type RuntimeEnv } from "openclaw/plugin-sdk/runtime-env"; import type { TelegramNativeCommandCallbackDispatcher, TelegramResolvedGroupConfig, } from "./bot-handlers.types.js"; -import { resolveTelegramMessageTurnSettings } from "./bot-message.js"; import { defaultTelegramNativeCommandDeps, type TelegramNativeCommandDeps, @@ -81,536 +30,21 @@ import { } from "./bot-native-command-menu.js"; import type { TelegramUpdateKeyContext } from "./bot-updates.js"; import type { TelegramBotOptions } from "./bot.types.js"; -import { - buildTelegramRoutingTarget, - buildTelegramThreadParams, - buildSenderName, - buildTelegramGroupFrom, - extractTelegramForumFlag, - isTelegramCommandsAllowFromConfigured, - resolveTelegramCommandAuthorization, - resolveTelegramForumFlag, - resolveTelegramGroupAllowFromContext, - resolveTelegramBotHasTopicsEnabled, - resolveTelegramMessageThreadSpec, - resolveTelegramThreadSpec, - shouldUseTelegramDmThreadSession, -} from "./bot/helpers.js"; -import type { TelegramGetChat } from "./bot/types.js"; -import type { TelegramInlineButtons } from "./button-types.js"; import { normalizeTelegramCommandName, resolveTelegramCustomCommands, TELEGRAM_COMMAND_NAME_PATTERN, } from "./command-config.js"; -import { - resolveTelegramConversationBaseSessionKey, - resolveTelegramConversationRoute, -} from "./conversation-route.js"; -import { shouldSuppressLocalTelegramExecApprovalPrompt } from "./exec-approvals.js"; -import { - evaluateTelegramGroupBaseAccess, - evaluateTelegramGroupPolicyAccess, -} from "./group-access.js"; -import { - resolveTelegramDirectToolPolicy, - resolveTelegramGroupPromptSettings, -} from "./group-config-helpers.js"; -import { resolveTelegramCommandIngressAuthorization } from "./ingress.js"; -import { buildInlineKeyboard } from "./inline-keyboard.js"; -import { buildTelegramNativeCommandCallbackData } from "./native-command-callback-data.js"; -import { recordSentMessage } from "./sent-message-cache.js"; -import { getTopicName, resolveTopicNameCacheScope } from "./topic-name-cache.js"; -export { parseTelegramNativeCommandCallbackData } from "./native-command-callback-data.js"; - -const EMPTY_RESPONSE_FALLBACK = "No response generated. Please try again."; -const NON_PLUGIN_COMMAND_DISPATCH = Object.freeze({ - kind: "non-plugin", -}) satisfies PluginCommandCatalogDecision; -const activeTelegramCodexLoginFlows = codexChannelLoginRuntime.createFlowRegistry(); +const loadTelegramBuiltinCommandExecutor = createLazyRuntimeModule( + () => import("./bot-native-command-builtins.js"), +); +const loadTelegramPluginCommandExecutor = createLazyRuntimeModule( + () => import("./bot-native-command-plugins.js"), +); type TelegramNativeCommandContext = Context & { match?: string }; -type TelegramChunkMode = ReturnType< - typeof import("openclaw/plugin-sdk/reply-dispatch-runtime").resolveChunkMode ->; -type TelegramNativeReplyPayload = import("openclaw/plugin-sdk/plugin-entry").PluginCommandResult; -type TelegramNativeReplyChannelData = { - buttons?: TelegramInlineButtons; - pin?: boolean; - reaction?: { - emoji?: unknown; - }; -}; -type FastModeState = ReturnType; - -type TelegramCommandAuthResult = { - chatId: number; - isGroup: boolean; - isForum: boolean; - resolvedThreadId?: number; - senderId: string; - senderUsername: string; - groupConfig?: TelegramGroupConfig | TelegramDirectConfig; - topicConfig?: TelegramTopicConfig; - commandAuthorized: boolean; - senderIsOwner: boolean; -}; - -type TelegramNativeCommandThreadContext = { - chatId: number; - isGroup: boolean; - isForum: boolean; - threadSpec: ReturnType; - threadParams: ReturnType; -}; - -type TelegramLoginDeviceCode = { - title: string; - code: string; - expiresInMinutes?: number; - message?: string; -}; - -// Telegram's inline-code entity provides the tap-to-copy affordance needed for -// short-lived device codes; plain text and literal backticks do not. -function formatTelegramLoginDeviceCode(params: TelegramLoginDeviceCode): string { - return [ - `${escapeHtml(params.title)}`, - "", - ...(params.message ? [escapeHtml(params.message)] : []), - `Code: ${escapeHtml(params.code)}`, - ...(params.expiresInMinutes - ? [`Code expires in ${params.expiresInMinutes} minutes. Never share it.`] - : []), - ].join("\n"); -} - -function resolveTelegramCodexLoginProviderInput(commandArgs: CommandArgs | undefined): string { - const providerValue = commandArgs?.values?.provider; - return typeof providerValue === "string" && providerValue.trim() - ? providerValue - : (commandArgs?.raw ?? "codex"); -} - -function buildTelegramCodexLoginFlowKey(params: { - accountId: string; - chatId: number; - threadSpec: ReturnType; - agentId: string; - provider: string; -}): string { - const threadKey = - params.threadSpec.id == null - ? params.threadSpec.scope - : `${params.threadSpec.scope}:${params.threadSpec.id}`; - return [ - "telegram", - params.accountId, - String(params.chatId), - threadKey, - params.agentId, - params.provider, - ].join(":"); -} - -type TelegramCommandMenuModelContext = { - provider?: string; - model?: string; - agentRuntime?: string; - thinkingLevel?: string; - fastMode?: SessionEntry["fastMode"]; -}; - -function buildTelegramCommandMenuModelContext(params: { - provider: string; - model: string; - thinkingLevel?: string; - fastMode?: SessionEntry["fastMode"]; -}): TelegramCommandMenuModelContext { - return { - provider: params.provider, - model: params.model, - ...(params.thinkingLevel ? { thinkingLevel: params.thinkingLevel } : {}), - ...(params.fastMode !== undefined ? { fastMode: params.fastMode } : {}), - }; -} - -const loadTelegramNativeCommandDeliveryRuntime = createLazyRuntimeModule( - () => import("./bot-native-commands.delivery.runtime.js"), -); - -const loadTelegramNativeCommandRuntime = createLazyRuntimeModule( - () => import("./bot-native-commands.runtime.js"), -); - -type TelegramNativeCommandRuntime = Awaited>; - -function resolveTelegramCommandSessionFile(params: { - agentId: string; - sessionId: string; - storePath: string; -}): string { - return formatSqliteSessionFileMarker({ - agentId: params.agentId, - sessionId: params.sessionId, - storePath: params.storePath, - }); -} - -async function resolveTelegramCommandTranscriptContext(params: { - cfg: OpenClawConfig; - agentId: string; - sessionKey: string; - threadId?: string | number; -}): Promise<{ sessionId?: string; sessionFile?: string; authProfileId?: string }> { - const sessionKey = params.sessionKey.trim(); - if (!sessionKey) { - return {}; - } - try { - const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); - const entry = getSessionEntry({ - agentId: params.agentId, - sessionKey, - storePath, - }); - const sessionId = entry?.sessionId?.trim() || randomUUID(); - const sessionFile = resolveTelegramCommandSessionFile({ - agentId: params.agentId, - sessionId, - storePath, - }); - const authProfileId = normalizeOptionalString(entry?.authProfileOverride); - return { - sessionId, - sessionFile, - ...(authProfileId ? { authProfileId } : {}), - }; - } catch { - return {}; - } -} - -function resolveTelegramCommandMenuModelContext(params: { - cfg: OpenClawConfig; - agentId: string; - sessionKey: string; -}): TelegramCommandMenuModelContext { - if (!params.sessionKey.trim()) { - return {}; - } - try { - const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); - const defaultModel = resolveDefaultModelForAgent({ - cfg: params.cfg, - agentId: params.agentId, - }); - const entry = getSessionEntry({ storePath, sessionKey: params.sessionKey }); - const thinkingLevel = normalizeOptionalString(entry?.thinkingLevel); - const fastMode = entry?.fastMode; - let context: TelegramCommandMenuModelContext; - if (entry?.modelOverrideSource === "auto" && normalizeOptionalString(entry.modelOverride)) { - context = buildTelegramCommandMenuModelContext({ - provider: defaultModel.provider, - model: defaultModel.model, - ...(thinkingLevel ? { thinkingLevel } : {}), - ...(fastMode !== undefined ? { fastMode } : {}), - }); - } else { - const override = resolveStoredModelOverride({ - sessionEntry: entry, - loadSessionEntry: (sessionKey) => getSessionEntry({ storePath, sessionKey }), - sessionKey: params.sessionKey, - defaultProvider: defaultModel.provider, - }); - if (override?.model) { - context = buildTelegramCommandMenuModelContext({ - provider: override.provider || defaultModel.provider, - model: override.model, - ...(thinkingLevel ? { thinkingLevel } : {}), - ...(fastMode !== undefined ? { fastMode } : {}), - }); - } else { - const provider = - normalizeOptionalString(entry?.providerOverride) ?? - normalizeOptionalString(entry?.modelProvider); - const model = - normalizeOptionalString(entry?.modelOverride) ?? normalizeOptionalString(entry?.model); - context = { - ...(provider ? { provider } : {}), - ...(model ? { model } : {}), - ...(thinkingLevel ? { thinkingLevel } : {}), - ...(fastMode !== undefined ? { fastMode } : {}), - }; - } - } - return { - ...context, - agentRuntime: resolveEffectiveAgentRuntime({ - cfg: params.cfg, - provider: context.provider ?? defaultModel.provider, - modelId: context.model ?? defaultModel.model, - agentId: params.agentId, - sessionKey: params.sessionKey, - sessionEntry: entry, - }), - }; - } catch { - return {}; - } -} - -function resolveTelegramFastCommandModelContext(params: { - cfg: OpenClawConfig; - agentId: string; - sessionKey: string; -}): { - provider?: string; - model?: string; -} { - const defaultModel = resolveDefaultModelForAgent({ - cfg: params.cfg, - agentId: params.agentId, - }); - const fallback = () => ({ - provider: defaultModel.provider, - model: defaultModel.model, - }); - if (!params.sessionKey.trim()) { - return fallback(); - } - try { - const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); - const entry = getSessionEntry({ storePath, sessionKey: params.sessionKey }); - if (entry?.modelOverrideSource === "auto" && normalizeOptionalString(entry.modelOverride)) { - return fallback(); - } - const override = resolveStoredModelOverride({ - sessionEntry: entry, - loadSessionEntry: (sessionKey) => getSessionEntry({ storePath, sessionKey }), - sessionKey: params.sessionKey, - defaultProvider: defaultModel.provider, - }); - return { - provider: override?.provider ?? defaultModel.provider, - model: override?.model ?? defaultModel.model, - }; - } catch { - return fallback(); - } -} - -function resolveTelegramFastCommandState(params: { - cfg: OpenClawConfig; - agentId: string; - sessionKey: string; -}): FastModeState { - const defaultModel = resolveDefaultModelForAgent({ - cfg: params.cfg, - agentId: params.agentId, - }); - const fallback = () => - resolveFastModeState({ - cfg: params.cfg, - provider: defaultModel.provider, - model: defaultModel.model, - agentId: params.agentId, - }); - if (!params.sessionKey.trim()) { - return fallback(); - } - try { - const storePath = resolveStorePath(params.cfg.session?.store, { agentId: params.agentId }); - const entry = getSessionEntry({ storePath, sessionKey: params.sessionKey }); - const modelContext = resolveTelegramFastCommandModelContext(params); - return resolveFastModeState({ - cfg: params.cfg, - provider: modelContext.provider ?? defaultModel.provider, - model: modelContext.model ?? defaultModel.model, - agentId: params.agentId, - sessionEntry: - entry?.fastMode !== undefined - ? { - fastMode: entry.fastMode, - } - : undefined, - }); - } catch { - return fallback(); - } -} - -async function resolveTelegramThinkMenuCurrentLevel(params: { - cfg: OpenClawConfig; - agentId: string; - provider?: string; - model?: string; - agentRuntime?: string; - thinkingLevel?: string; - catalog: Awaited>; -}): Promise { - const explicit = normalizeOptionalString(params.thinkingLevel); - if (explicit) { - return explicit; - } - const agentThinkingDefault = normalizeOptionalString( - resolveAgentConfig(params.cfg, params.agentId)?.thinkingDefault, - ); - if (agentThinkingDefault) { - return agentThinkingDefault; - } - const defaultModel = resolveDefaultModelForAgent({ - cfg: params.cfg, - agentId: params.agentId, - }); - return await resolveThinkingDefaultWithRuntimeCatalog({ - cfg: params.cfg, - provider: params.provider ?? defaultModel.provider, - model: params.model ?? defaultModel.model, - agentRuntime: params.agentRuntime, - loadRuntimeCatalog: async () => params.catalog, - }); -} - -function formatTelegramCommandArgMenuTitle(params: { - command: NonNullable>; - menu: NonNullable>; - currentThinkingLevel?: string; - currentFastModeStatus?: string; -}): string { - const title = formatCommandArgMenuTitle({ command: params.command, menu: params.menu }); - if (params.command.key === "think" && params.currentThinkingLevel) { - return `Current thinking level: ${params.currentThinkingLevel}.\n${title}`; - } - if (params.command.key === "fast" && params.currentFastModeStatus) { - const options = params.menu.choices - .map((choice) => choice.label.trim()) - .filter(Boolean) - .join(", "); - return options - ? `${params.currentFastModeStatus}\nOptions: ${options}.` - : params.currentFastModeStatus; - } - return title; -} - -function resolveTelegramFastMenuCurrentStatus(params: { state: FastModeState }): string { - return formatFastModeCurrentStatus({ - mode: params.state.mode, - source: params.state.source, - fastAutoOnSeconds: params.state.fastAutoOnSeconds, - }); -} - -function resolveTelegramNativeReplyChannelData( - result: TelegramNativeReplyPayload, -): TelegramNativeReplyChannelData | undefined { - return result.channelData?.telegram as TelegramNativeReplyChannelData | undefined; -} - -function normalizeTelegramNativeReplyPayload( - result: TelegramNativeReplyPayload | null | undefined, -): TelegramNativeReplyPayload { - return result && typeof result === "object" ? result : {}; -} - -function isSuppressedTelegramNativeReplyPayload(result: TelegramNativeReplyPayload): boolean { - return result.suppressReply === true; -} - -function hasTelegramNativeReplyReaction(result: TelegramNativeReplyPayload): boolean { - const reactionEmoji = resolveTelegramNativeReplyChannelData(result)?.reaction?.emoji; - return typeof reactionEmoji === "string" && reactionEmoji.trim().length > 0; -} - -function hasRenderableTelegramNativeReplyPayload(result: TelegramNativeReplyPayload): boolean { - const { channelData: _channelData, ...portableContent } = result; - if (hasOutboundReplyContent(portableContent, { trimText: true })) { - return true; - } - const telegramData = resolveTelegramNativeReplyChannelData(result); - return Boolean( - buildInlineKeyboard(telegramData?.buttons) || hasTelegramNativeReplyReaction(result), - ); -} - -function isEditableTelegramProgressResult(result: TelegramNativeReplyPayload): boolean { - const telegramData = resolveTelegramNativeReplyChannelData(result); - return Boolean( - typeof result.text === "string" && - result.text.trim() && - !result.mediaUrl && - (!result.mediaUrls || result.mediaUrls.length === 0) && - !result.presentation && - !result.interactive && - !result.btw && - !hasTelegramNativeReplyReaction(result) && - telegramData?.pin !== true, - ); -} - -async function cleanupTelegramProgressPlaceholder(params: { - bot: Bot; - chatId: number; - progressMessageId?: number; - runtime: RuntimeEnv; -}): Promise { - const progressMessageId = params.progressMessageId; - if (progressMessageId == null) { - return; - } - try { - await withTelegramApiErrorLogging({ - operation: "deleteMessage", - runtime: params.runtime, - fn: () => params.bot.api.deleteMessage(params.chatId, progressMessageId), - }); - } catch { - // Best-effort cleanup before fallback or suppression exits. - } -} - -async function resolveTelegramNativeCommandThreadContext(params: { - msg: NonNullable; - bot: Bot; -}): Promise { - const { msg, bot } = params; - const chatId = msg.chat.id; - const isGroup = msg.chat.type === "group" || msg.chat.type === "supergroup"; - const getChat = - typeof bot.api.getChat === "function" - ? (bot.api.getChat.bind(bot.api) as TelegramGetChat) - : undefined; - const isForum = - msg.chat.is_direct_messages === true - ? false - : await resolveTelegramForumFlag({ - chatId, - chatType: msg.chat.type, - isGroup, - isForum: extractTelegramForumFlag(msg.chat), - isTopicMessage: msg.is_topic_message, - getChat, - }); - const threadSpec = resolveTelegramMessageThreadSpec(msg, isForum); - return { - chatId, - isGroup, - isForum, - threadSpec, - threadParams: buildTelegramThreadParams(threadSpec), - }; -} - -function resolveTelegramNativeCommandDisableBlockStreaming( - telegramCfg: TelegramAccountConfig, -): boolean | undefined { - const blockStreamingEnabled = resolveChannelStreamingBlockEnabled(telegramCfg); - return typeof blockStreamingEnabled === "boolean" ? !blockStreamingEnabled : undefined; -} - type RegisterTelegramNativeCommandsParams = { bot: Bot; cfg: OpenClawConfig; @@ -634,229 +68,6 @@ type RegisterTelegramNativeCommandsParams = { >; }; -async function resolveTelegramCommandAuth(params: { - msg: NonNullable; - bot: Bot; - cfg: OpenClawConfig; - accountId: string; - telegramCfg: TelegramAccountConfig; - readChannelAllowFromStore: TelegramBotDeps["readChannelAllowFromStore"]; - allowFrom?: Array; - groupAllowFrom?: Array; - resolveGroupPolicy: (chatId: string | number, cfg: OpenClawConfig) => ChannelGroupPolicy; - resolveTelegramGroupConfig: ( - chatId: string | number, - messageThreadId: number | undefined, - cfg: OpenClawConfig, - ) => TelegramResolvedGroupConfig; - requireAuth: boolean; -}): Promise { - const { - msg, - bot, - cfg, - accountId, - telegramCfg, - readChannelAllowFromStore, - allowFrom, - groupAllowFrom, - resolveGroupPolicy, - resolveTelegramGroupConfig, - requireAuth, - } = params; - const { chatId, isGroup, isForum, threadSpec, threadParams } = - await resolveTelegramNativeCommandThreadContext({ msg, bot }); - const senderId = msg.from?.id ? String(msg.from.id) : ""; - const senderUsername = msg.from?.username ?? ""; - // Best-effort pre-context check: if commands.allowFrom already authorizes the - // sender at chat level, skip the pairing-store read so a transient store I/O - // failure cannot block a command this sender is explicitly allowed to run. - // resolvedThreadId is not known yet; the post-context check below is still - // the authoritative decision for topic-scoped command auth. - const commandsAllowFromConfigured = isTelegramCommandsAllowFromConfigured(cfg); - const preContextCommandsAllowFromAccess = commandsAllowFromConfigured - ? resolveTelegramCommandAuthorization({ - cfg, - accountId, - chatId, - isGroup, - senderId, - senderUsername, - }) - : null; - const groupAllowContext = await resolveTelegramGroupAllowFromContext({ - cfg, - chatId, - accountId, - dmPolicy: telegramCfg.dmPolicy, - allowFrom, - senderId, - isGroup, - threadSpec, - groupAllowFrom, - skipPairingStoreRead: Boolean(preContextCommandsAllowFromAccess?.isAuthorizedSender), - readChannelAllowFromStore, - resolveTelegramGroupConfig, - }); - const { - resolvedThreadId, - dmThreadId, - storeAllowFrom, - groupConfig, - topicConfig, - groupAllowOverride, - effectiveGroupAllow, - hasGroupAllowOverride, - } = groupAllowContext; - const effectiveDmPolicy = resolveTelegramEffectiveDmPolicy({ - isGroup, - groupConfig, - dmPolicy: telegramCfg.dmPolicy, - }); - const requireTopic = - !isGroup && groupConfig && "requireTopic" in groupConfig ? groupConfig.requireTopic : undefined; - if (!isGroup && requireTopic === true && dmThreadId == null) { - logVerbose(`Blocked telegram command in DM ${chatId}: requireTopic=true but no topic present`); - return null; - } - const dmAllowFrom = groupAllowOverride ?? allowFrom; - const commandsAllowFromAccess = commandsAllowFromConfigured - ? resolveTelegramCommandAuthorization({ - cfg, - accountId, - chatId, - isGroup, - resolvedThreadId, - senderId, - senderUsername, - }) - : null; - const ownerAccess = resolveTelegramCommandAuthorization({ - cfg, - accountId, - chatId, - isGroup, - resolvedThreadId, - senderId, - senderUsername, - }); - - const sendAuthMessage = async (text: string) => { - await withTelegramApiErrorLogging({ - operation: "sendMessage", - fn: () => bot.api.sendMessage(chatId, text, threadParams ?? {}), - }); - return null; - }; - const rejectNotAuthorized = async () => { - return await sendAuthMessage("You are not authorized to use this command."); - }; - - const baseAccess = evaluateTelegramGroupBaseAccess({ - isGroup, - groupConfig, - topicConfig, - hasGroupAllowOverride, - effectiveGroupAllow, - senderId, - senderUsername, - enforceAllowOverride: requireAuth, - requireSenderForAllowOverride: true, - }); - if (!baseAccess.allowed) { - if (baseAccess.reason === "group-disabled") { - logVerbose(`Blocked telegram command in group ${chatId} (group disabled)`); - return null; - } - if (baseAccess.reason === "topic-disabled") { - logVerbose( - `Blocked telegram command in topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`, - ); - return null; - } - return await rejectNotAuthorized(); - } - - const policyAccess = evaluateTelegramGroupPolicyAccess({ - isGroup, - chatId, - cfg, - telegramCfg, - topicConfig, - groupConfig, - effectiveGroupAllow, - senderId, - senderUsername, - resolveGroupPolicy, - enforcePolicy: true, - enforceAllowlistAuthorization: requireAuth && !commandsAllowFromConfigured, - allowEmptyAllowlistEntries: true, - requireSenderForAllowlistAuthorization: true, - checkChatAllowlist: true, - }); - if (!policyAccess.allowed) { - if (policyAccess.reason === "group-policy-disabled") { - logVerbose("Blocked telegram command (groupPolicy: disabled)"); - return null; - } - if ( - policyAccess.reason === "group-policy-allowlist-no-sender" || - policyAccess.reason === "group-policy-allowlist-unauthorized" - ) { - return await rejectNotAuthorized(); - } - if (policyAccess.reason === "group-chat-not-allowed") { - logVerbose(`Blocked telegram command in group ${chatId} (group not allowed)`); - return null; - } - } - - const expandedDmAllowFrom = await expandTelegramAllowFromWithAccessGroups({ - cfg, - allowFrom: dmAllowFrom, - accountId, - senderId, - }); - const dmAllow = normalizeDmAllowFromWithStore({ - allowFrom: expandedDmAllowFrom, - storeAllowFrom: isGroup ? [] : storeAllowFrom, - dmPolicy: effectiveDmPolicy, - }); - const commandAuthorized = commandsAllowFromConfigured - ? Boolean(commandsAllowFromAccess?.isAuthorizedSender) - : ( - await resolveTelegramCommandIngressAuthorization({ - accountId, - cfg, - dmPolicy: effectiveDmPolicy, - isGroup, - chatId, - resolvedThreadId, - senderId, - effectiveDmAllow: dmAllow, - effectiveGroupAllow, - ownerAccess, - eventKind: "native-command", - }) - ).authorized; - if (requireAuth && !commandAuthorized) { - return await rejectNotAuthorized(); - } - - return { - chatId, - isGroup, - isForum, - resolvedThreadId, - senderId, - senderUsername, - groupConfig, - topicConfig, - commandAuthorized, - senderIsOwner: ownerAccess.senderIsOwner, - }; -} - export const registerTelegramNativeCommands = ({ bot, cfg, @@ -883,10 +94,7 @@ export const registerTelegramNativeCommands = ({ } const skillCommands = nativeEnabled && nativeSkillsEnabled && boundRoute - ? telegramDeps.listSkillCommandsForAgents({ - cfg, - agentIds: [boundRoute.agentId], - }) + ? telegramDeps.listSkillCommandsForAgents({ cfg, agentIds: [boundRoute.agentId] }) : []; const pluginCommandRuntime = createPluginCommandRuntime(); const pluginCommandSpecs = pluginCommandRuntime.listNativeCandidates("telegram"); @@ -930,22 +138,17 @@ export const registerTelegramNativeCommands = ({ ); return null; } - const menuCommand: TelegramMenuCommand = { + return { command: normalized, description: command.description, + ...(command.isAlias ? { isAlias: true } : {}), + ...(index >= firstSkillCommandIndex ? { isSkill: true } : {}), + ...(command.descriptionLocalizations + ? { descriptionLocalizations: command.descriptionLocalizations } + : {}), }; - if (command.isAlias) { - menuCommand.isAlias = true; - } - if (index >= firstSkillCommandIndex) { - menuCommand.isSkill = true; - } - if (command.descriptionLocalizations) { - menuCommand.descriptionLocalizations = command.descriptionLocalizations; - } - return menuCommand; }) - .filter((cmd) => cmd !== null); + .filter((command) => command !== null); const customCommandNames = new Set(customCommands.map((command) => command.command)); const fullCommandCatalog = buildCappedTelegramMenuCommands({ allCommands: [ @@ -970,9 +173,6 @@ export const registerTelegramNativeCommands = ({ : loginCommand ? [loginCommand] : []; - const loadFreshRuntimeConfig = (): OpenClawConfig => telegramDeps.getRuntimeConfig(); - const resolveFreshTelegramConfig = (runtimeCfg: OpenClawConfig): TelegramAccountConfig => - resolveTelegramAccount({ cfg: runtimeCfg, accountId }).config; const { commandsToRegister, totalCommands, @@ -1001,8 +201,7 @@ export const registerTelegramNativeCommands = ({ } const syncTelegramMenuCommands = telegramDeps.syncTelegramMenuCommands ?? syncTelegramMenuCommandsRuntime; - // Telegram only limits the setMyCommands payload (menu entries). - // Keep hidden commands callable by registering handlers for the full catalog. + // Telegram only limits menu entries; hidden commands remain callable. syncTelegramMenuCommands({ bot, runtime, @@ -1012,143 +211,21 @@ export const registerTelegramNativeCommands = ({ botToken: opts.token, }); - const resolveCommandRuntimeContext = async (params: { - msg: NonNullable; - runtimeCfg: OpenClawConfig; - isGroup: boolean; - isForum: boolean; - resolvedThreadId?: number; - senderId?: string; - topicAgentId?: string; - }): Promise<{ - chatId: number; - threadSpec: ReturnType; - route: ReturnType["route"]; - mediaLocalRoots: readonly string[] | undefined; - tableMode: ReturnType; - chunkMode: TelegramChunkMode; - } | null> => { - const { msg, runtimeCfg, isGroup, isForum, resolvedThreadId, senderId, topicAgentId } = params; - const chatId = msg.chat.id; - const threadSpec = resolveTelegramMessageThreadSpec(msg, isForum); - const { route, bindingMode } = resolveTelegramConversationRoute({ - cfg: runtimeCfg, - accountId, - chatId, - isGroup, - resolvedThreadId, - replyThreadId: threadSpec.id, - senderId, - topicAgentId, - }); - const nativeCommandRuntime = await loadTelegramNativeCommandRuntime(); - if (bindingMode.kind === "configured") { - const ensured = await nativeCommandRuntime.ensureConfiguredBindingRouteReady({ - cfg: runtimeCfg, - bindingResolution: bindingMode.binding, - }); - if (!ensured.ok) { - logVerbose( - `telegram native command: configured ACP binding unavailable for topic ${bindingMode.binding.record.conversation.conversationId}: ${ensured.error}`, - ); - await withTelegramApiErrorLogging({ - operation: "sendMessage", - runtime, - fn: () => - bot.api.sendMessage( - chatId, - "Configured ACP binding is unavailable right now. Please try again.", - buildTelegramThreadParams(threadSpec) ?? {}, - ), - }); - return null; - } - } - const mediaLocalRoots = nativeCommandRuntime.getAgentScopedMediaLocalRoots( - runtimeCfg, - route.agentId, - ); - const tableMode = resolveMarkdownTableMode({ - cfg: runtimeCfg, - channel: "telegram", - accountId: route.accountId, - supportsBlockTables: true, - }); - const chunkMode = nativeCommandRuntime.resolveChunkMode( - runtimeCfg, - "telegram", - route.accountId, - ); - return { chatId, threadSpec, route, mediaLocalRoots, tableMode, chunkMode }; - }; - const buildCommandDeliveryBaseOptions = (params: { - cfg: OpenClawConfig; - chatId: string | number; - accountId: string; - sessionKeyForInternalHooks?: string; - policySessionKey?: string; - mirrorIsGroup?: boolean; - mirrorGroupId?: string; - mediaLocalRoots?: readonly string[]; - threadSpec: ReturnType; - tableMode: ReturnType; - chunkMode: TelegramChunkMode; - replyToMode: ReplyToMode; - textLimit: number; - linkPreview?: boolean; - richMessages?: boolean; + const buildExecutorParams = (params: { + botUser: Context["me"]; + msg: NonNullable; + rawText: string; }) => ({ - cfg: params.cfg, - chatId: String(params.chatId), - accountId: params.accountId, - sessionKeyForInternalHooks: params.sessionKeyForInternalHooks, - policySessionKey: params.policySessionKey, - mirrorIsGroup: params.mirrorIsGroup, - mirrorGroupId: params.mirrorGroupId, - token: opts.token, - runtime, + ...params, bot, - mediaLocalRoots: params.mediaLocalRoots, + runtime, + accountId, mediaMaxBytes, - replyToMode: params.replyToMode, - textLimit: params.textLimit, - thread: params.threadSpec, - tableMode: params.tableMode, - chunkMode: params.chunkMode, - linkPreview: params.linkPreview, - richMessages: params.richMessages, + resolveGroupPolicy, + resolveTelegramGroupConfig, + telegramDeps, + opts, }); - const resolveCommandTargetSessionKey = (params: { - runtimeCfg: OpenClawConfig; - route: ReturnType["route"]; - chatId: number; - isGroup: boolean; - senderId?: string; - threadSpec: ReturnType; - botHasTopicsEnabled?: boolean; - resolveThreadSessionKeys: TelegramNativeCommandRuntime["resolveThreadSessionKeys"]; - }): string => { - const baseSessionKey = resolveTelegramConversationBaseSessionKey({ - cfg: params.runtimeCfg, - route: params.route, - chatId: params.chatId, - isGroup: params.isGroup, - senderId: params.senderId, - }); - const dmThreadId = params.threadSpec.scope === "dm" ? params.threadSpec.id : undefined; - const threadKeys = - shouldUseTelegramDmThreadSession({ - dmThreadId, - botHasTopicsEnabled: params.botHasTopicsEnabled, - }) && dmThreadId != null - ? params.resolveThreadSessionKeys({ - baseSessionKey, - threadId: `${params.chatId}:${dmThreadId}`, - }) - : null; - return threadKeys?.sessionKey ?? baseSessionKey; - }; - let handleLoginCallback: | (( botUser: Context["me"], @@ -1156,918 +233,57 @@ export const registerTelegramNativeCommands = ({ rawText: string, ) => Promise) | undefined; - if (nativeCommandsToHandle.length > 0 || pluginCatalog.selectedCommands.length > 0) { - for (const command of nativeCommandsToHandle) { - const normalizedCommandName = normalizeTelegramCommandName(command.name); - const commandDefinition = findCommandByNativeName(command.name, "telegram"); - const handleNativeCommand = async ( - botUser: Context["me"], - msg: NonNullable, - rawText: string, - ): Promise => { - const runtimeCfg = loadFreshRuntimeConfig(); - const runtimeTelegramCfg = resolveFreshTelegramConfig(runtimeCfg); - const turnSettings = resolveTelegramMessageTurnSettings({ - accountId, - cfg: runtimeCfg, - telegramCfg: runtimeTelegramCfg, - opts, - }); - const auth = await resolveTelegramCommandAuth({ - msg, - bot, - cfg: runtimeCfg, - accountId, - telegramCfg: runtimeTelegramCfg, - readChannelAllowFromStore: telegramDeps.readChannelAllowFromStore, - allowFrom: turnSettings.allowFrom, - groupAllowFrom: turnSettings.groupAllowFrom, - resolveGroupPolicy, - resolveTelegramGroupConfig, - requireAuth: true, - }); - if (!auth) { - return false; - } - const { - chatId, - isGroup, - isForum, - resolvedThreadId, - senderId, - senderUsername, - groupConfig, - topicConfig, - commandAuthorized, - senderIsOwner, - } = auth; - const runtimeContext = await resolveCommandRuntimeContext({ - msg, - runtimeCfg, - isGroup, - isForum, - resolvedThreadId, - senderId, - topicAgentId: topicConfig?.agentId, - }); - if (!runtimeContext) { - return false; - } - const { threadSpec, route, mediaLocalRoots, tableMode, chunkMode } = runtimeContext; - const threadParams = buildTelegramThreadParams(threadSpec) ?? {}; - const originatingTo = buildTelegramRoutingTarget(chatId, threadSpec); - const commandArgs = commandDefinition - ? parseCommandArgs(commandDefinition, rawText) - : rawText - ? ({ raw: rawText } satisfies CommandArgs) - : undefined; - const prompt = commandDefinition - ? buildCommandTextFromArgs(commandDefinition, commandArgs) - : rawText - ? `/${command.name} ${rawText}` - : `/${command.name}`; - - if (commandDefinition?.key === "login") { - const sendLoginMessage = async (text: string) => { - await withTelegramApiErrorLogging({ - operation: "sendMessage", - runtime, - fn: () => bot.api.sendMessage(chatId, text, threadParams), - }); - }; - const sendLoginDeviceCode = async (params: TelegramLoginDeviceCode) => { - await withTelegramApiErrorLogging({ - operation: "sendMessage", - runtime, - fn: () => - bot.api.sendMessage(chatId, formatTelegramLoginDeviceCode(params), { - ...threadParams, - parse_mode: "HTML", - }), - }); - }; - const sendLoginResultMessage = async (text: string) => { - await telegramDeps.sendMessageTelegram( - buildTelegramRoutingTarget(chatId, threadSpec), - text, - { - cfg: runtimeCfg, - token: opts.token, - accountId: route.accountId, - }, - ); - }; - if ( - !senderIsOwner || - !codexChannelLoginRuntime.hasConfiguredCommandOwnerAllowlist(runtimeCfg) - ) { - await sendLoginMessage( - "Only a configured OpenClaw owner can start Codex login from Telegram.", - ); - return false; - } - if (isGroup) { - await sendLoginMessage( - "For safety, Codex login codes are only sent in a private chat with this bot. DM this bot `/login codex` to pair Codex.", - ); - return true; - } - const loginProvider = codexChannelLoginRuntime.resolveProvider( - resolveTelegramCodexLoginProviderInput(commandArgs), - ); - if (!loginProvider) { - await sendLoginMessage("Unsupported login provider. Use `/login codex`."); - return false; - } - const flowKey = buildTelegramCodexLoginFlowKey({ - accountId: route.accountId, - chatId, - threadSpec, - agentId: route.agentId, - provider: loginProvider, - }); - const reservation = codexChannelLoginRuntime.reserveFlow({ - flows: activeTelegramCodexLoginFlows, - flowKey, - }); - if (reservation.status === "active") { - await sendLoginMessage( - "A Codex login code is already active for this Telegram chat. Complete it, or wait for it to expire before requesting a new one.", - ); - return true; - } - const flowSignal = opts.accountAbortSignal - ? AbortSignal.any([reservation.record.signal, opts.accountAbortSignal]) - : reservation.record.signal; - const deviceCodeDelivered = createDeferred(); - let deviceCodeWasDelivered = false; - // Device-code delivery releases Telegram's serialized chat lane. The - // reservation and account signal still own polling through completion. - const completion = (async () => { - const sessionSwitchFailedMessage = - "Codex login completed, but this Telegram session could not switch to the newly authenticated profile. Retry `/login codex`, or select the profile manually."; - let terminalMessage: string; - const loginFlow = - telegramDeps.runModelsAuthLoginFlow ?? - defaultTelegramNativeCommandDeps.runModelsAuthLoginFlow; - try { - if (!loginFlow) { - throw new Error("Codex login flow is unavailable."); - } - const nativeCommandRuntime = await loadTelegramNativeCommandRuntime(); - const targetSessionKey = resolveCommandTargetSessionKey({ - runtimeCfg, - route, - chatId, - isGroup, - senderId, - threadSpec, - botHasTopicsEnabled: resolveTelegramBotHasTopicsEnabled(botUser), - resolveThreadSessionKeys: nativeCommandRuntime.resolveThreadSessionKeys, - }); - const targetSessionEntryAtStart = nativeCommandRuntime.getSessionEntry({ - agentId: route.agentId, - sessionKey: targetSessionKey, - }); - const loginResult = await codexChannelLoginRuntime.runDeviceLoginFlow({ - runLoginFlow: loginFlow, - provider: loginProvider, - agentId: route.agentId, - config: runtimeCfg, - runtime, - signal: flowSignal, - sendMessage: sendLoginMessage, - sendDeviceCode: async (deviceCode) => { - flowSignal.throwIfAborted(); - await sendLoginDeviceCode(deviceCode); - flowSignal.throwIfAborted(); - deviceCodeWasDelivered = true; - deviceCodeDelivered.resolve(); - }, - unsupportedPromptMessage: - "Telegram /login supports only fixed Codex device-code auth.", - }); - flowSignal.throwIfAborted(); - const nextProfileId = loginResult.profiles.find( - (profile) => profile.provider === loginProvider, - )?.profileId; - terminalMessage = "Codex login complete. Try your request again now."; - if (!nextProfileId) { - terminalMessage = sessionSwitchFailedMessage; - } else { - const storePath = resolveStorePath(runtimeCfg.session?.store, { - agentId: route.agentId, - }); - let entryObserved = false; - let adoptionAllowed = false; - try { - const persisted = await updateSessionStoreEntry({ - sessionKey: targetSessionKey, - storePath, - requireWriteSuccess: true, - skipMaintenance: true, - update: (entry) => { - entryObserved = true; - const source = - entry.authProfileOverrideSource ?? - (typeof entry.authProfileOverrideCompactionCount === "number" - ? "auto" - : entry.authProfileOverride - ? "user" - : undefined); - if ( - flowSignal.aborted || - (targetSessionEntryAtStart - ? entry.sessionId !== targetSessionEntryAtStart.sessionId || - entry.authProfileOverride !== - targetSessionEntryAtStart.authProfileOverride || - entry.authProfileOverrideSource !== - targetSessionEntryAtStart.authProfileOverrideSource || - entry.authProfileOverrideCompactionCount !== - targetSessionEntryAtStart.authProfileOverrideCompactionCount - : source === "user" && entry.authProfileOverride !== nextProfileId) - ) { - return null; - } - adoptionAllowed = true; - return entry.authProfileOverride !== nextProfileId || - entry.authProfileOverrideSource !== "user" || - entry.authProfileOverrideCompactionCount !== undefined - ? { - authProfileOverride: nextProfileId, - authProfileOverrideSource: "user", - authProfileOverrideCompactionCount: undefined, - } - : null; - }, - }); - flowSignal.throwIfAborted(); - if ( - entryObserved && - (!adoptionAllowed || - !persisted || - persisted.authProfileOverride !== nextProfileId || - persisted.authProfileOverrideSource !== "user" || - persisted.authProfileOverrideCompactionCount !== undefined) - ) { - terminalMessage = sessionSwitchFailedMessage; - } - } catch (error) { - flowSignal.throwIfAborted(); - runtime.error?.( - danger( - `telegram /login codex completed but failed to update session auth profile: ${String( - error, - )}`, - ), - ); - terminalMessage = sessionSwitchFailedMessage; - } - } - } catch (error) { - if (flowSignal.aborted) { - return; - } - runtime.error?.(danger(`telegram /login codex failed: ${String(error)}`)); - terminalMessage = - "Codex login did not complete. Send `/login codex` to request a new code."; - } - if (flowSignal.aborted) { - return; - } - try { - await sendLoginResultMessage(terminalMessage); - } catch (error) { - runtime.error?.( - danger(`telegram /login codex result notification failed: ${String(error)}`), - ); - } - })().finally(() => { - codexChannelLoginRuntime.releaseFlow({ - flows: activeTelegramCodexLoginFlows, - flowKey, - record: reservation.record, - }); - }); - await Promise.race([deviceCodeDelivered.promise, completion]); - return deviceCodeWasDelivered; - } - - let cachedTargetSessionKey: string | undefined; - let cachedNativeCommandRuntime: - | Awaited> - | undefined; - const resolveNativeCommandRuntime = async () => { - cachedNativeCommandRuntime ??= await loadTelegramNativeCommandRuntime(); - return cachedNativeCommandRuntime; - }; - const resolveTargetSessionKey = async (): Promise => { - if (cachedTargetSessionKey) { - return cachedTargetSessionKey; - } - cachedTargetSessionKey = resolveCommandTargetSessionKey({ - runtimeCfg, - route, - chatId, - isGroup, - senderId, - threadSpec, - botHasTopicsEnabled: resolveTelegramBotHasTopicsEnabled(botUser), - resolveThreadSessionKeys: (await resolveNativeCommandRuntime()) - .resolveThreadSessionKeys, - }); - return cachedTargetSessionKey; - }; - const menuNeedsModelContext = - commandDefinition?.argsMenu && - !(commandArgs?.raw && !commandArgs.values) && - commandDefinition.args?.some( - (arg) => typeof arg.choices === "function" && commandArgs?.values?.[arg.name] == null, - ); - const targetSessionKeyForMenu = - commandDefinition && menuNeedsModelContext ? await resolveTargetSessionKey() : ""; - const fastCommandState = - commandDefinition?.key === "fast" && menuNeedsModelContext - ? resolveTelegramFastCommandState({ - cfg: runtimeCfg, - agentId: route.agentId, - sessionKey: targetSessionKeyForMenu, - }) - : undefined; - const fastMenuModelContext = - commandDefinition?.key === "fast" && menuNeedsModelContext - ? resolveTelegramFastCommandModelContext({ - cfg: runtimeCfg, - agentId: route.agentId, - sessionKey: targetSessionKeyForMenu, - }) - : undefined; - const menuModelContext = - commandDefinition && menuNeedsModelContext - ? (fastMenuModelContext ?? - resolveTelegramCommandMenuModelContext({ - cfg: runtimeCfg, - agentId: route.agentId, - sessionKey: targetSessionKeyForMenu, - })) - : {}; - // Native /think must not wait on provider discovery; persisted rows retain its metadata. - const menuModelCatalog = - commandDefinition?.key === "think" && menuNeedsModelContext - ? await loadPreparedModelCatalog({ - config: runtimeCfg, - agentId: route.agentId, - agentDir: resolveAgentDir(runtimeCfg, route.agentId), - readOnly: true, - }) - : undefined; - const menu = commandDefinition - ? resolveCommandArgMenu({ - command: commandDefinition, - args: commandArgs, - cfg: runtimeCfg, - ...menuModelContext, - ...(menuModelCatalog?.length ? { catalog: menuModelCatalog } : {}), - }) - : null; - if (menu && commandDefinition) { - const title = formatTelegramCommandArgMenuTitle({ - command: commandDefinition, - menu, - currentThinkingLevel: - commandDefinition.key === "think" - ? await resolveTelegramThinkMenuCurrentLevel({ - cfg: runtimeCfg, - agentId: route.agentId, - ...menuModelContext, - catalog: menuModelCatalog ?? [], - }) - : undefined, - currentFastModeStatus: - commandDefinition.key === "fast" - ? resolveTelegramFastMenuCurrentStatus({ - state: - fastCommandState ?? - resolveTelegramFastCommandState({ - cfg: runtimeCfg, - agentId: route.agentId, - sessionKey: targetSessionKeyForMenu, - }), - }) - : undefined, - }); - const rows: Array> = []; - for (let i = 0; i < menu.choices.length; i += 2) { - const slice = menu.choices.slice(i, i + 2); - rows.push( - slice.map((choice) => { - const args: CommandArgs = { - values: { [menu.arg.name]: choice.value }, - }; - return { - text: choice.label, - callback_data: buildTelegramNativeCommandCallbackData( - buildCommandTextFromArgs(commandDefinition, args), - ), - }; - }), - ); - } - const replyMarkup = buildInlineKeyboard(rows); - await withTelegramApiErrorLogging({ - operation: "sendMessage", - runtime, - fn: () => - bot.api.sendMessage(chatId, title, { - ...(replyMarkup ? { reply_markup: replyMarkup } : {}), - ...threadParams, - }), - }); - return false; - } - const nativeCommandRuntime = await resolveNativeCommandRuntime(); - const sessionKey = await resolveTargetSessionKey(); - const { skillFilter, groupSystemPrompt } = resolveTelegramGroupPromptSettings({ - groupConfig, - topicConfig, - }); - const { sessionKey: commandSessionKey, commandTargetSessionKey } = - resolveNativeCommandSessionTargets({ - agentId: route.agentId, - sessionPrefix: "telegram:slash", - userId: String(senderId || chatId), - targetSessionKey: sessionKey, - }); - const deliveryBaseOptions = buildCommandDeliveryBaseOptions({ - cfg: runtimeCfg, - chatId, - accountId: route.accountId, - sessionKeyForInternalHooks: commandSessionKey, - policySessionKey: commandTargetSessionKey, - mirrorIsGroup: isGroup, - mirrorGroupId: isGroup ? String(chatId) : undefined, - mediaLocalRoots, - threadSpec, - tableMode, - chunkMode, - replyToMode: turnSettings.replyToMode, - textLimit: turnSettings.textLimit, - linkPreview: runtimeTelegramCfg.linkPreview, - richMessages: runtimeTelegramCfg.richMessages, - }); - let topicName: string | undefined; - if (isForum && resolvedThreadId != null) { - try { - const storePath = resolveStorePath(runtimeCfg.session?.store, { - agentId: route.accountId, - }); - const scope = resolveTopicNameCacheScope(storePath); - topicName = await getTopicName(chatId, resolvedThreadId, scope); - } catch { - // best-effort: topic name is supplementary metadata - } - } - const conversationLabel = isGroup - ? msg.chat.title - ? `${msg.chat.title} id:${chatId}` - : `group:${chatId}` - : (buildSenderName(msg) ?? String(senderId || chatId)); - const ctxPayload = nativeCommandRuntime.finalizeInboundContext({ - Body: prompt, - BodyForAgent: prompt, - RawBody: prompt, - CommandBody: prompt, - CommandArgs: commandArgs, - From: isGroup ? buildTelegramGroupFrom(chatId, resolvedThreadId) : `telegram:${chatId}`, - To: `slash:${senderId || chatId}`, - ChatType: isGroup ? "group" : "direct", - ConversationToolPolicy: isGroup - ? undefined - : resolveTelegramDirectToolPolicy({ - directConfig: groupConfig, - senderId, - senderName: buildSenderName(msg), - senderUsername, - }), - ConversationLabel: conversationLabel, - GroupSubject: isGroup ? (msg.chat.title ?? undefined) : undefined, - GroupSystemPrompt: isGroup || (!isGroup && groupConfig) ? groupSystemPrompt : undefined, - SenderName: buildSenderName(msg), - SenderId: senderId || undefined, - SenderUsername: senderUsername || undefined, - Surface: "telegram", - Provider: "telegram", - MessageSid: String(msg.message_id), - Timestamp: msg.date ? msg.date * 1000 : undefined, - WasMentioned: true, - CommandAuthorized: commandAuthorized, - CommandTurn: { - kind: "native" as const, - source: "native" as const, - authorized: commandAuthorized, - body: prompt, - }, - CommandSource: "native" as const, - SessionKey: commandSessionKey, - AccountId: route.accountId, - CommandTargetSessionKey: commandTargetSessionKey, - MessageThreadId: threadSpec.id, - IsForum: isForum, - TopicName: isForum && topicName ? topicName : undefined, - // Originating context for sub-agent announce routing - OriginatingChannel: "telegram" as const, - OriginatingTo: originatingTo, - }); - const disableBlockStreaming = - resolveTelegramNativeCommandDisableBlockStreaming(runtimeTelegramCfg); - const deliveryState = { - delivered: false, - skippedNonSilent: 0, - failedNonSilent: 0, - }; - let finalReplyOutcome: "accepted" | "failed" | "suppressed" | undefined; - - const { deliverReplies } = await loadTelegramNativeCommandDeliveryRuntime(); - let recordSessionMetaTask: Promise | undefined; - - const turnPlan: ChannelInboundTurnPlan<"provider_message_sending"> = { - cfg: runtimeCfg, - channel: "telegram", - accountId: route.accountId, - route: { - agentId: route.agentId, - sessionKey: commandSessionKey, - }, - ctxPayload, - record: { - sessionKey: commandTargetSessionKey, - trackSessionMetaTask: (task) => { - recordSessionMetaTask = task; - }, - onRecordError: (err) => - runtime.error?.( - danger(`telegram slash: failed updating session meta: ${String(err)}`), - ), - }, - // Native commands historically persisted target metadata before dispatch. - // Preserve that ordering while the shared recorder owns the write. - afterRecord: async () => { - await recordSessionMetaTask; - }, - replyPipeline: {}, - dispatcherOptions: { - beforeDeliver: async (payload) => payload, - onSkip: (_payload, info) => { - if (info.reason !== "silent") { - deliveryState.skippedNonSilent += 1; - } - }, - }, - delivery: { - deliverWithProviderMessageSending: async (payload, info) => { - if ( - shouldSuppressLocalTelegramExecApprovalPrompt({ - cfg: runtimeCfg, - accountId: route.accountId, - payload, - }) - ) { - deliveryState.delivered = true; - return { - visibleReplySent: false, - suppression: { reason: "no_visible_result" }, - }; - } - const targetedPayload = payload.replyToId - ? payload - : { ...payload, replyToId: String(msg.message_id) }; - const result = await deliverReplies({ - // Bind custody so a lost response on the native-command path is - // recorded as ambiguous instead of silently unaccounted. - replies: [ - info.bindPendingFinalDelivery - ? info.bindPendingFinalDelivery(targetedPayload) - : targetedPayload, - ], - ...deliveryBaseOptions, - silent: runtimeTelegramCfg.silentErrorReplies === true && payload.isError === true, - onPlatformSendDispatch: info.onPlatformSendDispatch, - }); - if (result.delivered) { - deliveryState.delivered = true; - } - return result.delivered - ? { visibleReplySent: true } - : { - visibleReplySent: false, - suppression: { reason: "no_visible_result" as const }, - }; - }, - onDelivered: (_payload, info, result) => { - const reason = result?.suppression?.reason; - if (info.kind === "final" && result?.visibleReplySent) { - finalReplyOutcome = "accepted"; - } - if ( - info.kind === "final" && - finalReplyOutcome !== "failed" && - (reason === "cancelled_by_reply_payload_sending_hook" || - reason === "empty_after_reply_payload_sending_hook") - ) { - finalReplyOutcome = "suppressed"; - } - }, - onError: (err, info) => { - deliveryState.failedNonSilent += 1; - const partialDelivery = isChannelPartialDeliveryError(err); - if (partialDelivery) { - deliveryState.delivered = true; - logVerbose("telegram slash reply partially delivered before failure"); - } - if (info.kind === "final") { - // A failed final outweighs any earlier suppression until a final delivers. - finalReplyOutcome = partialDelivery ? "accepted" : "failed"; - } - runtime.error?.(danger(`telegram slash ${info.kind} reply failed: ${String(err)}`)); - }, - }, - replyOptions: { - skillFilter, - disableBlockStreaming, - [PLUGIN_COMMAND_DISPATCH]: NON_PLUGIN_COMMAND_DISPATCH, - }, - }; - const turnResult = await ( - telegramDeps.dispatchChannelInboundTurn ?? - defaultTelegramNativeCommandDeps.dispatchChannelInboundTurn - )(turnPlan); - if ( - !deliveryState.delivered && - finalReplyOutcome !== "suppressed" && - (deliveryState.skippedNonSilent > 0 || deliveryState.failedNonSilent > 0) && - (!turnResult.dispatched || - turnResult.dispatchResult.sourceReplyDeliveryMode !== "message_tool_only" || - deliveryState.failedNonSilent > 0) - ) { - await deliverReplies({ - replies: [{ text: EMPTY_RESPONSE_FALLBACK }], - ...deliveryBaseOptions, - }); - } - return false; - }; - if (nativeEnabled) { - bot.command(normalizedCommandName, async (ctx) => { - if (shouldSkipUpdate(ctx)) { - return; - } - const msg = ctx.message; - if (!msg) { - return; - } - await handleNativeCommand( - ctx.me, - msg, - typeof ctx.match === "string" ? ctx.match.trim() : "", - ); - }); - } - if (commandDefinition?.key === "login") { - handleLoginCallback = handleNativeCommand; - } - } - - for (const pluginCommand of pluginCatalog.selectedCommands) { - bot.command(pluginCommand.command, async (ctx: TelegramNativeCommandContext) => { - const msg = ctx.message; - if (!msg) { + for (const command of nativeCommandsToHandle) { + const normalizedCommandName = normalizeTelegramCommandName(command.name); + const handleNativeCommand = async ( + botUser: Context["me"], + msg: NonNullable, + rawText: string, + ): Promise => { + const { executeTelegramBuiltinCommand } = await loadTelegramBuiltinCommandExecutor(); + return await executeTelegramBuiltinCommand({ + ...buildExecutorParams({ botUser, msg, rawText }), + commandName: command.name, + }); + }; + if (nativeEnabled) { + bot.command(normalizedCommandName, async (ctx) => { + if (shouldSkipUpdate(ctx) || !ctx.message) { return; } - if (shouldSkipUpdate(ctx)) { - return; - } - const chatId = msg.chat.id; - const runtimeCfg = loadFreshRuntimeConfig(); - const runtimeTelegramCfg = resolveFreshTelegramConfig(runtimeCfg); - const turnSettings = resolveTelegramMessageTurnSettings({ - accountId, - cfg: runtimeCfg, - telegramCfg: runtimeTelegramCfg, - opts, - }); - const { threadParams } = await resolveTelegramNativeCommandThreadContext({ msg, bot }); - const rawText = ctx.match?.trim() ?? ""; - const commandBody = `/${pluginCommand.command}${rawText ? ` ${rawText}` : ""}`; - const candidate = pluginCommand.spec; - const pluginCommandDispatch = candidate.prepareDispatch(rawText); - if (pluginCommandDispatch.kind === "non-plugin") { - await withTelegramApiErrorLogging({ - operation: "sendMessage", - runtime, - fn: () => bot.api.sendMessage(chatId, "Command not found.", threadParams ?? {}), - }); - return; - } - const nativeCommandRuntime = await loadTelegramNativeCommandRuntime(); - const auth = await resolveTelegramCommandAuth({ - msg, - bot, - cfg: runtimeCfg, - accountId, - telegramCfg: runtimeTelegramCfg, - readChannelAllowFromStore: telegramDeps.readChannelAllowFromStore, - allowFrom: turnSettings.allowFrom, - groupAllowFrom: turnSettings.groupAllowFrom, - resolveGroupPolicy, - resolveTelegramGroupConfig, - requireAuth: candidate.requireAuth, - }); - if (!auth) { - return; - } - const { senderId, commandAuthorized, senderIsOwner, isGroup, isForum, resolvedThreadId } = - auth; - const runtimeContext = await resolveCommandRuntimeContext({ - msg, - runtimeCfg, - isGroup, - isForum, - resolvedThreadId, - senderId, - topicAgentId: auth.topicConfig?.agentId, - }); - if (!runtimeContext) { - return; - } - const { threadSpec, route, mediaLocalRoots, tableMode, chunkMode } = runtimeContext; - const targetSessionKey = resolveCommandTargetSessionKey({ - runtimeCfg, - route, - chatId, - isGroup, - senderId, - threadSpec, - botHasTopicsEnabled: resolveTelegramBotHasTopicsEnabled(ctx.me), - resolveThreadSessionKeys: nativeCommandRuntime.resolveThreadSessionKeys, - }); - const targetSessionEntry = nativeCommandRuntime.getSessionEntry({ - agentId: route.agentId, - sessionKey: targetSessionKey, - }); - const deliveryBaseOptions = buildCommandDeliveryBaseOptions({ - cfg: runtimeCfg, - chatId, - accountId: route.accountId, - sessionKeyForInternalHooks: targetSessionKey, - policySessionKey: targetSessionKey, - mirrorIsGroup: isGroup, - mirrorGroupId: isGroup ? String(chatId) : undefined, - mediaLocalRoots, - threadSpec, - tableMode, - chunkMode, - replyToMode: turnSettings.replyToMode, - textLimit: turnSettings.textLimit, - linkPreview: runtimeTelegramCfg.linkPreview, - richMessages: runtimeTelegramCfg.richMessages, - }); - const from = isGroup ? buildTelegramGroupFrom(chatId, threadSpec.id) : `telegram:${chatId}`; - const to = - threadSpec.scope === "direct-messages" - ? buildTelegramRoutingTarget(chatId, threadSpec) - : `telegram:${chatId}`; - const { deliverReplies, emitTelegramMessageSentHooks } = - await loadTelegramNativeCommandDeliveryRuntime(); - let progressMessageId: number | undefined; - const progressPlaceholder = candidate.progressMessage; - - if (progressPlaceholder) { - try { - const sent = await withTelegramApiErrorLogging({ - operation: "sendMessage", - runtime, - fn: () => - bot.api.sendMessage( - chatId, - progressPlaceholder, - buildTelegramThreadParams(threadSpec), - ), - }); - const maybeMessageId = (sent as { message_id?: unknown } | undefined)?.message_id; - if (typeof maybeMessageId === "number") { - progressMessageId = maybeMessageId; - } - } catch { - // Fall back to the normal final reply path if the placeholder send fails. - } - } - - const transcriptContext = await resolveTelegramCommandTranscriptContext({ - cfg: runtimeCfg, - agentId: route.agentId, - sessionKey: targetSessionKey, - threadId: threadSpec.id, - }); - - const result = normalizeTelegramNativeReplyPayload( - await pluginCommandDispatch.execute({ - senderId, - channel: "telegram", - isAuthorizedSender: commandAuthorized, - senderIsOwner, - agentId: route.agentId, - sessionKey: targetSessionKey, - sessionId: transcriptContext.sessionId, - sessionFile: transcriptContext.sessionFile, - authProfileId: - transcriptContext.authProfileId ?? targetSessionEntry?.authProfileOverride, - commandBody, - config: runtimeCfg, - from, - to, - accountId, - messageThreadId: threadSpec.id, - }), + await handleNativeCommand( + ctx.me, + ctx.message, + typeof ctx.match === "string" ? ctx.match.trim() : "", ); - - const suppressTelegramNativeReply = - shouldSuppressLocalTelegramExecApprovalPrompt({ - cfg: runtimeCfg, - accountId: route.accountId, - payload: result, - }) || isSuppressedTelegramNativeReplyPayload(result); - if (suppressTelegramNativeReply) { - await cleanupTelegramProgressPlaceholder({ - bot, - chatId, - progressMessageId, - runtime, - }); - return; - } - - const hasReaction = hasTelegramNativeReplyReaction(result); - const deliverableResult: TelegramNativeReplyPayload = - hasRenderableTelegramNativeReplyPayload(result) - ? hasReaction && !normalizeOptionalString(result.replyToId) - ? { ...result, replyToId: String(msg.message_id) } - : result - : { text: EMPTY_RESPONSE_FALLBACK }; - const progressResultText = - typeof deliverableResult.text === "string" && deliverableResult.text.trim().length > 0 - ? deliverableResult.text - : null; - const telegramResultData = resolveTelegramNativeReplyChannelData(deliverableResult); - if ( - progressMessageId != null && - telegramDeps.editMessageTelegram && - progressResultText && - isEditableTelegramProgressResult(deliverableResult) - ) { - try { - await telegramDeps.editMessageTelegram(chatId, progressMessageId, progressResultText, { - cfg: runtimeCfg, - accountId: route.accountId, - textMode: "markdown", - linkPreview: runtimeTelegramCfg.linkPreview, - buttons: telegramResultData?.buttons, - }); - recordSentMessage(chatId, progressMessageId, runtimeCfg); - emitTelegramMessageSentHooks({ - sessionKeyForInternalHooks: targetSessionKey, - chatId: String(chatId), - accountId: route.accountId, - content: progressResultText, - success: true, - messageId: progressMessageId, - isGroup, - groupId: isGroup ? String(chatId) : undefined, - }); - return; - } catch { - // Fall through to cleanup + normal delivered reply if editing fails. - } - } - await cleanupTelegramProgressPlaceholder({ - bot, - chatId, - progressMessageId, - runtime, - }); - await deliverReplies({ - replies: [deliverableResult], - ...deliveryBaseOptions, - ...(hasReaction ? { replyToMode: "all" as const } : {}), - silent: - runtimeTelegramCfg.silentErrorReplies === true && deliverableResult.isError === true, - }); }); } - if (pluginCatalog.selectedCommands.length > 0) { - pluginCommandRuntime.retainNativeCatalog("telegram"); + if (findCommandByNativeName(command.name, "telegram")?.key === "login") { + handleLoginCallback = handleNativeCommand; } } + for (const pluginCommand of pluginCatalog.selectedCommands) { + bot.command(pluginCommand.command, async (ctx: TelegramNativeCommandContext) => { + if (shouldSkipUpdate(ctx) || !ctx.message) { + return; + } + const { executeTelegramPluginCommand } = await loadTelegramPluginCommandExecutor(); + await executeTelegramPluginCommand({ + ...buildExecutorParams({ + botUser: ctx.me, + msg: ctx.message, + rawText: ctx.match?.trim() ?? "", + }), + commandName: pluginCommand.command, + candidate: pluginCommand.spec, + }); + }); + } + if (pluginCatalog.selectedCommands.length > 0) { + pluginCommandRuntime.retainNativeCatalog("telegram"); + } + if (!handleLoginCallback) { return undefined; } @@ -2087,19 +303,20 @@ export const registerTelegramNativeCommands = ({ if (!callbackMessage || callbackMessage.date <= 0) { return { handled: true, clearButtons: false }; } - const chat = callbackMessage.chat; - if (chat.type === "channel") { + if (callbackMessage.chat.type === "channel") { return { handled: true, clearButtons: false }; } const rawText = separatorIndex === -1 ? "" : commandBody.slice(separatorIndex + 1).trim(); - const message = { - ...callbackMessage, - chat, - from: callbackQuery.from, - text: commandText, - }; - const clearButtons = await handleLoginCallback(botUser, message, rawText); + const clearButtons = await handleLoginCallback( + botUser, + { + ...callbackMessage, + chat: callbackMessage.chat, + from: callbackQuery.from, + text: commandText, + }, + rawText, + ); return { handled: true, clearButtons }; }; }; -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/extensions/telegram/src/conversation-route.ts b/extensions/telegram/src/conversation-route.ts index da796726467b..ad4762da6b5b 100644 --- a/extensions/telegram/src/conversation-route.ts +++ b/extensions/telegram/src/conversation-route.ts @@ -9,12 +9,17 @@ import { buildAgentSessionKey, deriveLastRoutePolicy, resolveAgentRoute, + resolveThreadSessionKeys, } from "openclaw/plugin-sdk/routing"; import { buildAgentMainSessionKey, sanitizeAgentId } from "openclaw/plugin-sdk/routing"; import { logVerbose } from "openclaw/plugin-sdk/runtime-env"; import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime"; import { resolveDefaultTelegramAccountId } from "./accounts.js"; -import { buildTelegramGroupPeerId, buildTelegramParentPeer } from "./bot/helpers.js"; +import { + buildTelegramGroupPeerId, + buildTelegramParentPeer, + shouldUseTelegramDmThreadSession, +} from "./bot/helpers.js"; import { resolveTelegramDirectPeerId, resolveTelegramNamedAccountBaseSessionKey, @@ -162,3 +167,26 @@ export function resolveTelegramConversationBaseSessionKey( params, ); } + +export function resolveTelegramTargetSession(params: { + cfg: OpenClawConfig; + route: TelegramResolvedRoute; + chatId: number | string; + isGroup: boolean; + senderId?: string | number | null; + dmThreadId?: number; + botHasTopicsEnabled?: boolean; +}): string { + const baseSessionKey = resolveTelegramConversationBaseSessionKey(params); + const threadKeys = + shouldUseTelegramDmThreadSession({ + dmThreadId: params.dmThreadId, + botHasTopicsEnabled: params.botHasTopicsEnabled, + }) && params.dmThreadId != null + ? resolveThreadSessionKeys({ + baseSessionKey, + threadId: `${params.chatId}:${params.dmThreadId}`, + }) + : null; + return threadKeys?.sessionKey ?? baseSessionKey; +} diff --git a/extensions/telegram/src/native-command-callback-data.test.ts b/extensions/telegram/src/native-command-callback-data.test.ts new file mode 100644 index 000000000000..253582f0a8c2 --- /dev/null +++ b/extensions/telegram/src/native-command-callback-data.test.ts @@ -0,0 +1,11 @@ +import { describe, expect, it } from "vitest"; +import { parseTelegramNativeCommandCallbackData } from "./native-command-callback-data.js"; + +describe("parseTelegramNativeCommandCallbackData", () => { + it("preserves prefixed native commands and rejects malformed command bodies", () => { + expect(parseTelegramNativeCommandCallbackData("tgcmd:/fast status")).toBe("/fast status"); + expect(parseTelegramNativeCommandCallbackData("tgcmd:/fast auto")).toBe("/fast auto"); + expect(parseTelegramNativeCommandCallbackData("tgcmd:/fast default")).toBe("/fast default"); + expect(parseTelegramNativeCommandCallbackData("tgcmd:fast status")).toBeNull(); + }); +}); From a3b2700dff451c7451aac64ee03e70d4a1be2d1b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:46:22 -0700 Subject: [PATCH 013/165] fix(deps): bump @openclaw/fs-safe to 0.5.5 for win32 zero-inode identity (#122427) --- extensions/onepassword/package.json | 2 +- package.json | 2 +- pnpm-lock.yaml | 14 +++++++------- pnpm-workspace.yaml | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/extensions/onepassword/package.json b/extensions/onepassword/package.json index 7bd9d2d28d83..9d87e7b146b2 100644 --- a/extensions/onepassword/package.json +++ b/extensions/onepassword/package.json @@ -5,7 +5,7 @@ "description": "1Password SecretRef resolver and audited agent secrets broker for OpenClaw", "type": "module", "dependencies": { - "@openclaw/fs-safe": "0.5.4", + "@openclaw/fs-safe": "0.5.5", "execa": "10.0.0" }, "devDependencies": { diff --git a/package.json b/package.json index 1dfaed270448..92805a628d8e 100644 --- a/package.json +++ b/package.json @@ -2026,7 +2026,7 @@ "@modelcontextprotocol/sdk": "1.30.0", "@mozilla/readability": "0.6.0", "@openclaw/ai": "workspace:*", - "@openclaw/fs-safe": "0.5.4", + "@openclaw/fs-safe": "0.5.5", "@openclaw/proxyline": "0.3.4", "@silvia-odwyer/photon-node": "0.3.4", "@trycua/cua-driver": "0.14.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b567698b434b..04deda2564f5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -89,8 +89,8 @@ importers: specifier: workspace:* version: link:packages/ai '@openclaw/fs-safe': - specifier: 0.5.4 - version: 0.5.4 + specifier: 0.5.5 + version: 0.5.5 '@openclaw/proxyline': specifier: 0.3.4 version: 0.3.4(undici@8.9.0) @@ -1487,8 +1487,8 @@ importers: extensions/onepassword: dependencies: '@openclaw/fs-safe': - specifier: 0.5.4 - version: 0.5.4 + specifier: 0.5.5 + version: 0.5.5 execa: specifier: 10.0.0 version: 10.0.0 @@ -4107,8 +4107,8 @@ packages: engines: {node: '>=22'} hasBin: true - '@openclaw/fs-safe@0.5.4': - resolution: {integrity: sha512-lttlWKRBQU7eYDYykU2BPoF1S6AESGrT77mVCXsuWBxnRBTAI/PuGB89DB3D1lBCDaqTykIjymPJz4pFesGnkg==} + '@openclaw/fs-safe@0.5.5': + resolution: {integrity: sha512-x8wYigrOwmnsE8v4LfAh2eTvvkuDMspBrQeBp/GyB9/c7eFf8aL7gK4keewDbhscKX1pACD8Yd+ehZq6o29xHw==} engines: {node: '>=22'} '@openclaw/libterminal@0.3.2': @@ -11395,7 +11395,7 @@ snapshots: - bufferutil - utf-8-validate - '@openclaw/fs-safe@0.5.4': + '@openclaw/fs-safe@0.5.5': optionalDependencies: jszip: 3.10.1 tar: 7.5.22 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index ea050d19072a..956c1f5c971e 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -9,7 +9,7 @@ minimumReleaseAge: 2880 minimumReleaseAgeExclude: - "@openclaw/crabline@0.1.11" - - "@openclaw/fs-safe@0.5.4" + - "@openclaw/fs-safe@0.5.5" - "@openclaw/libterminal@0.3.2" - "@openclaw/proxyline@0.3.4" - "@openclaw/uirouter@0.1.1" From b82ad646a5151e5fb6378e72dbbe257fd5012813 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:47:44 -0700 Subject: [PATCH 014/165] fix(delivery): preserve suppressed send outcomes (#122421) * fix(delivery): preserve suppressed send outcomes Preserve authoritative durable-send suppression outcomes so task, subagent, and exec followups no longer report false delivery or duplicate ambiguous adapter dispatches. * fix(delivery): keep suppression reason internal Derive the outbound projection from the existing durable batch result union so the repair does not change the public plugin SDK contract. * fix(delivery): avoid retrying ambiguous task updates Advance the state-change event cursor after an adapter returns no identity so a possibly visible progress notification is not sent twice; intentional suppression remains retryable. --- .../bash-tools.exec-approval-followup.test.ts | 51 +++++++++++++ .../bash-tools.exec-approval-followup.ts | 12 +++- .../subagent-announce-delivery.test.ts | 39 ++++++++++ .../announce/subagent-announce-delivery.ts | 20 +++++- src/infra/outbound/message.test.ts | 66 +++++++++-------- src/infra/outbound/message.ts | 3 + src/tasks/task-registry-delivery.ts | 34 ++++++++- src/tasks/task-registry.test.ts | 72 +++++++++++++++++++ 8 files changed, 261 insertions(+), 36 deletions(-) diff --git a/src/agents/bash-tools.exec-approval-followup.test.ts b/src/agents/bash-tools.exec-approval-followup.test.ts index 9805e1e558d6..04e196edeb37 100644 --- a/src/agents/bash-tools.exec-approval-followup.test.ts +++ b/src/agents/bash-tools.exec-approval-followup.test.ts @@ -758,6 +758,57 @@ describe("exec approval followup", () => { expect(callGatewayTool).not.toHaveBeenCalled(); }); + it.each([ + { + suppressionReason: "cancelled_by_message_sending_hook", + expectedMessage: "delivery was suppressed", + }, + { + suppressionReason: "adapter_returned_no_identity", + expectedMessage: "delivery could not be confirmed", + }, + ] as const)( + "rejects direct followup after $suppressionReason", + async ({ suppressionReason, expectedMessage }) => { + vi.mocked(sendMessage).mockResolvedValueOnce({ + channel: "discord", + to: "123", + via: "direct", + mediaUrl: null, + deliveryStatus: "suppressed", + suppressionReason, + }); + + await expect( + sendExecApprovalFollowup({ + approvalId: `req-${suppressionReason}`, + turnSourceChannel: "discord", + turnSourceTo: "123", + resultText: "Exec finished (gateway id=req-suppressed, code 0)\nall good", + }), + ).rejects.toThrow(expectedMessage); + }, + ); + + it("accepts direct followup success without a delivery status", async () => { + vi.mocked(sendMessage).mockResolvedValueOnce({ + channel: "discord", + to: "123", + via: "gateway", + mediaUrl: null, + result: { messageId: "gateway-message-1" }, + }); + + await expect( + sendExecApprovalFollowup({ + approvalId: "req-gateway-compatible", + turnSourceChannel: "discord", + turnSourceTo: "123", + resultText: "Exec finished (gateway id=req-gateway-compatible, code 0)\nall good", + }), + ).resolves.toBe(true); + }); + it("redacts credentials before direct delivery", async () => { const secret = "sk-abcdefghijklmnopqrstuvwxyz123456"; diff --git a/src/agents/bash-tools.exec-approval-followup.ts b/src/agents/bash-tools.exec-approval-followup.ts index 51a7da95fa70..2bc8b5b3b28b 100644 --- a/src/agents/bash-tools.exec-approval-followup.ts +++ b/src/agents/bash-tools.exec-approval-followup.ts @@ -414,7 +414,7 @@ async function sendDirectFollowupFallback(params: { Math.max(0, directText.length - Math.max(1, availableBodyUnits)), )}`; const deliveryIntentId = `exec-approval-followup:${params.approvalId}`; - await sendMessage({ + const sendResult = await sendMessage({ channel: params.deliveryTarget.channel, to: params.deliveryTarget.to ?? "", accountId: params.deliveryTarget.accountId, @@ -427,6 +427,16 @@ async function sendDirectFollowupFallback(params: { reusePendingDeliveryIntent: true, completionRetention: DIRECT_FOLLOWUP_COMPLETION_RETENTION, }); + if (sendResult.deliveryStatus === "suppressed") { + if (sendResult.suppressionReason === "adapter_returned_no_identity") { + throw new Error( + "exec approval followup delivery could not be confirmed: adapter returned no identity", + ); + } + throw new Error( + `exec approval followup delivery was suppressed: ${sendResult.suppressionReason ?? "unknown reason"}`, + ); + } return true; } diff --git a/src/agents/subagents/announce/subagent-announce-delivery.test.ts b/src/agents/subagents/announce/subagent-announce-delivery.test.ts index 06ef1df4719c..b5278199db03 100644 --- a/src/agents/subagents/announce/subagent-announce-delivery.test.ts +++ b/src/agents/subagents/announce/subagent-announce-delivery.test.ts @@ -1313,6 +1313,45 @@ describe("deliverSubagentAnnouncement completion delivery", () => { } }); + it.each([ + { + name: "intentional suppression", + suppressionReason: "cancelled_by_message_sending_hook", + disposition: "intentional_non_delivery", + }, + { + name: "adapter ambiguity", + suppressionReason: "adapter_returned_no_identity", + disposition: "ambiguous", + }, + ] as const)("reports $name from direct text completion fallback", async (testCase) => { + const callGateway = createPayloadGatewayMock(); + const onDeliveryResult = vi.fn(); + const sendMessage = vi.fn(async () => ({ + channel: "discord", + to: "dm:U123", + via: "direct" as const, + mediaUrl: null, + deliveryStatus: "suppressed" as const, + suppressionReason: testCase.suppressionReason, + })) as unknown as typeof runtimeSendMessage; + + const result = await deliverDiscordDirectMessageCompletion({ + callGateway, + sendMessage, + internalEvents: taskCompletionEvents({ childSessionId: "child-session-id" }), + onDeliveryResult, + }); + + expectRecordFields(result, { + delivered: false, + path: "direct", + disposition: testCase.disposition, + }); + expect(onDeliveryResult).not.toHaveBeenCalled(); + expect(sendMessage).toHaveBeenCalledTimes(1); + }); + it("sanitizes and bounds text before direct completion fallback delivery", async () => { const callGateway = createPayloadGatewayMock(); const sendMessage = createSendMessageMock(); diff --git a/src/agents/subagents/announce/subagent-announce-delivery.ts b/src/agents/subagents/announce/subagent-announce-delivery.ts index fe79d3368fca..9002834d6c2f 100644 --- a/src/agents/subagents/announce/subagent-announce-delivery.ts +++ b/src/agents/subagents/announce/subagent-announce-delivery.ts @@ -760,7 +760,7 @@ async function deliverCompletionDirect(params: { if (params.isSourceSessionEffectsAllowed?.() === false) { return sourceOwnerChangedResult(); } - await subagentAnnounceDeliveryDeps.sendMessage({ + const sendResult = await subagentAnnounceDeliveryDeps.sendMessage({ cfg: params.cfg, channel: params.deliveryTarget.channel, to: params.deliveryTarget.to, @@ -786,7 +786,23 @@ async function deliverCompletionDirect(params: { idempotencyKey, }, }); - return committedDelivery ?? { delivered: true, path: "direct" }; + if (committedDelivery) { + return committedDelivery; + } + if (sendResult.deliveryStatus === "suppressed") { + const ambiguous = sendResult.suppressionReason === "adapter_returned_no_identity"; + return { + delivered: false, + path: "direct", + error: ambiguous + ? "text completion direct delivery could not be confirmed: adapter returned no identity" + : `text completion direct delivery was suppressed: ${sendResult.suppressionReason ?? "unknown reason"}`, + ...(ambiguous + ? { disposition: "ambiguous" as const } + : { disposition: "intentional_non_delivery" as const, terminal: true }), + }; + } + return { delivered: true, path: "direct" }; } catch (err) { if (committedDelivery) { // Post-send bookkeeping must never turn an identified delivery into a diff --git a/src/infra/outbound/message.test.ts b/src/infra/outbound/message.test.ts index cf37eea5e0b3..1a0764673565 100644 --- a/src/infra/outbound/message.test.ts +++ b/src/infra/outbound/message.test.ts @@ -554,40 +554,44 @@ describe("sendMessage", () => { expectDeliveryCallFields({ to: "prepared:123456" }); }); - it("preserves suppressed direct-send status", async () => { - mocks.deliverOutboundPayloads.mockImplementationOnce(async (params: unknown) => { - const callbacks = params as { - onPayloadDeliveryOutcome?: (outcome: unknown) => void; - }; - callbacks.onPayloadDeliveryOutcome?.({ - index: 0, - status: "suppressed", - reason: "cancelled_by_message_sending_hook", - hookEffect: { - cancelReason: "owned-by-other-agent", - metadata: { unsafeForJson: 1n }, - }, + it.each(["cancelled_by_message_sending_hook", "adapter_returned_no_identity"] as const)( + "preserves aggregate suppression reason %s", + async (reason) => { + mocks.deliverOutboundPayloads.mockImplementationOnce(async (params: unknown) => { + const callbacks = params as { + onPayloadDeliveryOutcome?: (outcome: unknown) => void; + }; + callbacks.onPayloadDeliveryOutcome?.({ + index: 0, + status: "suppressed", + reason, + hookEffect: { + cancelReason: "owned-by-other-agent", + metadata: { unsafeForJson: 1n }, + }, + }); + return []; }); - return []; - }); - const result = await sendMessage({ - cfg: {}, - channel: "forum", - to: "123456", - content: "hidden", - }); + const result = await sendMessage({ + cfg: {}, + channel: "forum", + to: "123456", + content: "hidden", + }); - expect(result.deliveryStatus).toBe("suppressed"); - expect(result.payloadOutcomes).toEqual([ - { - index: 0, - status: "suppressed", - reason: "cancelled_by_message_sending_hook", - }, - ]); - expect(() => JSON.stringify(result)).not.toThrow(); - }); + expect(result.deliveryStatus).toBe("suppressed"); + expect(result).toMatchObject({ suppressionReason: reason }); + expect(result.payloadOutcomes).toEqual([ + { + index: 0, + status: "suppressed", + reason, + }, + ]); + expect(() => JSON.stringify(result)).not.toThrow(); + }, + ); it("does not throw best-effort direct send failures but reports the failure", async () => { mocks.deliverOutboundPayloads.mockImplementationOnce(async (params: unknown) => { diff --git a/src/infra/outbound/message.ts b/src/infra/outbound/message.ts index 77e712ba3912..e574599696e7 100644 --- a/src/infra/outbound/message.ts +++ b/src/infra/outbound/message.ts @@ -6,6 +6,7 @@ import { deriveDurableFinalDeliveryRequirementsForBatch } from "../../channels/m import { sendDurableMessageBatchCore, serializeDurableMessagePayloadOutcomes, + type DurableMessageBatchSendResult, type SerializedDurableMessagePayloadOutcome, } from "../../channels/message/runtime.js"; import type { DurableMessageSendIntent } from "../../channels/message/types.js"; @@ -129,6 +130,7 @@ export type MessageSendResult = { mediaUrls?: string[]; result?: OutboundDeliveryResult | { messageId: string }; deliveryStatus?: "sent" | "suppressed" | "partial_failed" | "failed"; + suppressionReason?: Extract["reason"]; /** Formatted send error when deliveryStatus is "failed" or "partial_failed". */ error?: string; sentBeforeError?: boolean; @@ -441,6 +443,7 @@ export async function sendMessage(params: MessageSendParams): Promise { }); }); + it.each([ + { + name: "intentional suppression queues the session fallback", + suppressionReason: "cancelled_by_message_sending_hook", + expectedFallbackCount: 1, + }, + { + name: "adapter ambiguity avoids a duplicate session fallback", + suppressionReason: "adapter_returned_no_identity", + expectedFallbackCount: 0, + }, + ] as const)("records terminal non-delivery when $name", async (testCase) => { + await withTaskRegistryTempDir(async () => { + hoisted.sendMessageMock.mockResolvedValue({ + channel: "notifychat", + to: "notifychat:123", + via: "direct", + deliveryStatus: "suppressed", + suppressionReason: testCase.suppressionReason, + }); + const task = createTaskFixture("acp", { + requesterOrigin: NOTIFYCHAT_ORIGIN, + runId: `run-terminal-${testCase.suppressionReason}`, + task: "Investigate suppressed delivery", + deliveryStatus: "pending", + }); + markTaskTerminalById({ taskId: task.taskId, status: "succeeded", endedAt: 250 }); + + await maybeDeliverTaskTerminalUpdate(task.taskId); + + expectRecordFields(requireTaskById(task.taskId), { deliveryStatus: "failed" }); + expect(peekSystemEvents("agent:main:main")).toHaveLength(testCase.expectedFallbackCount); + }); + }); + it("still wakes the parent when blocked delivery misses the outward channel", async () => { await withTaskRegistryTempDir(async () => { resetTaskRegistryMemoryForTest(); @@ -3965,6 +4000,43 @@ describe("task-registry", () => { }); }); + it.each([ + { + name: "retries intentional suppression", + suppressionReason: "cancelled_by_message_sending_hook", + expectedSendCount: 2, + }, + { + name: "does not retry adapter ambiguity", + suppressionReason: "adapter_returned_no_identity", + expectedSendCount: 1, + }, + ] as const)("$name for the same state-change event", async (testCase) => { + await withTaskRegistryTempDir(async () => { + hoisted.sendMessageMock.mockResolvedValue({ + channel: "guildchat", + to: "guildchat:123", + via: "direct", + deliveryStatus: "suppressed", + suppressionReason: testCase.suppressionReason, + }); + const task = createTaskFixture("acp", { + deliveryStatus: undefined, + requesterOrigin: GUILDCHAT_ORIGIN, + childSessionKey: "agent:codex:acp:child", + runId: "run-state-change-suppressed", + task: "Investigate suppressed state change", + notifyPolicy: "state_changes", + }); + const event = { at: 250, kind: "progress" as const, summary: "Still working." }; + + await maybeDeliverTaskStateChangeUpdate(task.taskId, event); + await maybeDeliverTaskStateChangeUpdate(task.taskId, event); + + expect(hoisted.sendMessageMock).toHaveBeenCalledTimes(testCase.expectedSendCount); + }); + }); + it("keeps background ACP progress off the foreground lane and only sends a terminal notify", async () => { await withTaskRegistryTempDir(async () => { resetTaskRegistryMemoryForTest(); From f6459a325561f2754019b5fcd8f29383d789fdbf Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:49:47 -0700 Subject: [PATCH 015/165] refactor(ui): split chat thread into transcript owners (#122420) * refactor(ui): split chat thread into transcript owners * refactor(ui): delete orphaned pinned-messages surface * chore(lint): ratchet max-lines baseline after chat-thread split * fix(ui): tighten transcript owner type boundaries * refactor(ui): prune pinned-message orphans --- config/max-lines-baseline.txt | 1 - test/vitest/vitest.ui-isolated-paths.mjs | 4 +- ui/src/i18n/locales/en.ts | 2 - ui/src/pages/chat/chat-pane-base.ts | 2 +- ui/src/pages/chat/chat-pane-lifecycle.test.ts | 4 +- ui/src/pages/chat/chat-pane-render.ts | 1 - .../chat/chat-pane-retained-presentation.ts | 4 +- ui/src/pages/chat/chat-thread.test.ts | 212 -- ui/src/pages/chat/chat-view-state.ts | 4 +- ui/src/pages/chat/chat-view.test-helpers.ts | 2 +- ui/src/pages/chat/chat-view.test.ts | 18 +- ui/src/pages/chat/chat-view.ts | 31 +- .../components/chat-thread-interactions.ts | 562 +++++ .../components/chat-thread.measure.test.ts | 909 -------- ui/src/pages/chat/components/chat-thread.ts | 1984 +---------------- .../chat-transcript-controller.test.ts | 197 ++ .../components/chat-transcript-controller.ts | 670 ++++++ .../chat-transcript-invalidation.test.ts | 507 +++++ .../components/chat-transcript-projection.ts | 681 ++++++ .../components/chat-transcript-render.test.ts | 271 +++ .../chat-transcript.test-support.ts | 121 + ui/src/pages/chat/persisted-set.ts | 46 - ui/src/pages/chat/pinned-messages.ts | 30 - 23 files changed, 3064 insertions(+), 3199 deletions(-) create mode 100644 ui/src/pages/chat/components/chat-thread-interactions.ts delete mode 100644 ui/src/pages/chat/components/chat-thread.measure.test.ts create mode 100644 ui/src/pages/chat/components/chat-transcript-controller.test.ts create mode 100644 ui/src/pages/chat/components/chat-transcript-controller.ts create mode 100644 ui/src/pages/chat/components/chat-transcript-invalidation.test.ts create mode 100644 ui/src/pages/chat/components/chat-transcript-projection.ts create mode 100644 ui/src/pages/chat/components/chat-transcript-render.test.ts create mode 100644 ui/src/pages/chat/components/chat-transcript.test-support.ts delete mode 100644 ui/src/pages/chat/persisted-set.ts delete mode 100644 ui/src/pages/chat/pinned-messages.ts diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt index 27753e029aa0..ebe7313541c6 100644 --- a/config/max-lines-baseline.txt +++ b/config/max-lines-baseline.txt @@ -909,7 +909,6 @@ ui/src/pages/chat/chat-view.test.ts ui/src/pages/chat/components/chat-message.test.ts ui/src/pages/chat/components/chat-session-workspace.ts ui/src/pages/chat/components/chat-sidebar.ts -ui/src/pages/chat/components/chat-thread.ts ui/src/pages/chat/components/chat-tool-cards.ts ui/src/pages/chat/composer-persistence.test.ts ui/src/pages/chat/composer-persistence.ts diff --git a/test/vitest/vitest.ui-isolated-paths.mjs b/test/vitest/vitest.ui-isolated-paths.mjs index 045f4e160d18..881ed3adc149 100644 --- a/test/vitest/vitest.ui-isolated-paths.mjs +++ b/test/vitest/vitest.ui-isolated-paths.mjs @@ -20,7 +20,9 @@ export const uiIsolatedTestFiles = [ "ui/src/pages/chat/chat-pane.read-marker.test.ts", "ui/src/pages/chat/chat-pane.session-discussion.test.ts", "ui/src/pages/chat/chat-pane.test.ts", - "ui/src/pages/chat/components/chat-thread.measure.test.ts", + "ui/src/pages/chat/components/chat-transcript-controller.test.ts", + "ui/src/pages/chat/components/chat-transcript-invalidation.test.ts", + "ui/src/pages/chat/components/chat-transcript-render.test.ts", "ui/src/pages/config/config-page.custom-theme.test.ts", "ui/src/pages/config/memory-mutation-owner.test.ts", "ui/src/pages/config/memory-page.test.ts", diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts index fd6fc1e386ce..01268476e9ea 100644 --- a/ui/src/i18n/locales/en.ts +++ b/ui/src/i18n/locales/en.ts @@ -5093,10 +5093,8 @@ export const en: TranslationMap = { search: "Search messages", searchPlaceholder: "Search messages...", closeSearch: "Close search", - unpin: "Unpin", loading: "Loading chat", noMatches: "No matching messages", - pinnedCount: "{count} pinned", }, pairingQrExpired: { title: "Pairing QR expired", diff --git a/ui/src/pages/chat/chat-pane-base.ts b/ui/src/pages/chat/chat-pane-base.ts index 67517f87b787..46b85af406d1 100644 --- a/ui/src/pages/chat/chat-pane-base.ts +++ b/ui/src/pages/chat/chat-pane-base.ts @@ -57,7 +57,7 @@ import type { ChatPageHost } from "./chat-state-host.ts"; import type { ChatPaneHeaderAction } from "./components/chat-pane-header.ts"; import type { SessionRailCommand, SessionRailMode } from "./components/chat-session-rail.ts"; import type { ChatSessionSharingState } from "./components/chat-session-sharing.ts"; -import { ChatTranscriptController } from "./components/chat-thread.ts"; +import { ChatTranscriptController } from "./components/chat-transcript-controller.ts"; import type { SessionDiscussionPanelConfig } from "./components/session-discussion-panel.ts"; import type { ChatMessageCache } from "./session-message-cache.ts"; diff --git a/ui/src/pages/chat/chat-pane-lifecycle.test.ts b/ui/src/pages/chat/chat-pane-lifecycle.test.ts index 2e9aec9414a5..baf9325e494c 100644 --- a/ui/src/pages/chat/chat-pane-lifecycle.test.ts +++ b/ui/src/pages/chat/chat-pane-lifecycle.test.ts @@ -22,7 +22,7 @@ import { dismissConfirmedActionPopovers, openChatRewindConfirmation, } from "./components/chat-message.ts"; -import * as chatThread from "./components/chat-thread.ts"; +import * as chatThread from "./components/chat-thread-interactions.ts"; import { prepareInitialUserMessageHandoff } from "./initial-turn-handoff.ts"; const SKIP_REWIND_CONFIRM_PREFERENCE = "openclaw:skip-rewind-confirm"; @@ -709,7 +709,7 @@ afterEach(() => { owner.remove(); } confirmationOwners.clear(); - chatThread.resetChatThreadPresentationState(); + chatThread.resetThreadPresentation(); window.localStorage.removeItem(SKIP_REWIND_CONFIRM_PREFERENCE); vi.unstubAllGlobals(); }); diff --git a/ui/src/pages/chat/chat-pane-render.ts b/ui/src/pages/chat/chat-pane-render.ts index edb5269253f1..c5ccb817002d 100644 --- a/ui/src/pages/chat/chat-pane-render.ts +++ b/ui/src/pages/chat/chat-pane-render.ts @@ -602,7 +602,6 @@ export class ChatPane extends ChatPaneBrowserAnnotationRender { assistantAttachmentAuthToken: resolveAssistantAttachmentAuthToken(state as never), resolveArtifactDownload: (params) => resolveChatArtifactDownload(state, params), basePath: state.basePath, - gatewayUrl: state.settings.gatewayUrl, }; const chat = renderChat(props); const primary = this.renderBoardPrimary(board, chat); diff --git a/ui/src/pages/chat/chat-pane-retained-presentation.ts b/ui/src/pages/chat/chat-pane-retained-presentation.ts index 097139100e74..4be8b39a658a 100644 --- a/ui/src/pages/chat/chat-pane-retained-presentation.ts +++ b/ui/src/pages/chat/chat-pane-retained-presentation.ts @@ -12,7 +12,7 @@ import { setChatError } from "./chat-send-queue-state.ts"; import { refreshCurrentChatSessionList } from "./chat-session.ts"; import { invalidateImageLightbox } from "./chat-state-page.ts"; import { dismissConfirmedActionPopovers } from "./components/chat-message.ts"; -import { resetChatThreadSessionPresentationState } from "./components/chat-thread.ts"; +import { resetTranscriptSession } from "./components/chat-thread-interactions.ts"; import { CHAT_COMPOSER_DRAFT_STORAGE_ERROR } from "./composer-persistence.ts"; /** Owns the resources and composer state that follow one retained presentation. */ @@ -58,7 +58,7 @@ export abstract class ChatPaneRetainedPresentation extends ChatPaneBoard { this.settleResetConfirmation(false); this.cancelHeaderRename(); dismissConfirmedActionPopovers(this); - resetChatThreadSessionPresentationState(this.presentationId, this); + resetTranscriptSession(this.presentationId, this); const state = this.state; if (state) { stopChatRealtimeTalk(state); diff --git a/ui/src/pages/chat/chat-thread.test.ts b/ui/src/pages/chat/chat-thread.test.ts index 2ea70f14a6bb..07aabeb88a99 100644 --- a/ui/src/pages/chat/chat-thread.test.ts +++ b/ui/src/pages/chat/chat-thread.test.ts @@ -3867,218 +3867,6 @@ describe("expansion-state render dependencies", () => { resetChatThreadState(); expect(getExpansionStateVersion(getExpandedUserMessages("reset-session"))).toBe(0); }); - - it("keeps mounted disclosure handlers attached to recreated session expansion maps", async () => { - resetChatThreadState(); - const { builtinEnvironments } = await import("vitest/runtime"); - const fixtureGlobals = ["Request", "URL", "jsdom"] as const; - const originalFixtureGlobals = fixtureGlobals.map( - (name) => [name, Object.getOwnPropertyDescriptor(globalThis, name)] as const, - ); - const originalDocument = Object.getOwnPropertyDescriptor(globalThis, "document"); - const originalWindow = Object.getOwnPropertyDescriptor(globalThis, "window"); - let environment: Awaited> | undefined; - - try { - environment = await builtinEnvironments.jsdom.setup(globalThis, { - jsdom: { url: "http://localhost/", pretendToBeVisual: true }, - }); - const [{ render }, { ChatTranscriptController, resetChatThreadPresentationState }] = - await Promise.all([import("lit"), import("./components/chat-thread.ts")]); - const host = { - addController() {}, - removeController() {}, - requestUpdate() {}, - updateComplete: Promise.resolve(true), - }; - const sessionKey = "retained-session"; - const props = { - paneId: "retained-pane", - sessionKey, - loading: false, - messages: [ - { role: "user", content: "long user message ".repeat(100), timestamp: 1 }, - { - role: "assistant", - content: [ - { type: "text", text: "assistant reply" }, - { type: "toolcall", id: "retained-call", name: "browser.open" }, - ], - timestamp: 2, - }, - ], - toolMessages: [], - streamSegments: [], - stream: null, - streamStartedAt: null, - queue: [], - showThinking: false, - showToolCalls: true, - sessions: null, - assistantName: "Molty", - assistantAvatar: null, - onDraftChange() {}, - onSend() {}, - }; - const controller = new ChatTranscriptController(host); - const retainedPane = document.createElement("div"); - document.body.append(retainedPane); - render(controller.render(props), retainedPane); - const staleTools = getExpandedToolCards(sessionKey); - const staleUsers = getExpandedUserMessages(sessionKey); - const previousToolVersion = getExpansionStateVersion(staleTools); - const previousUserVersion = getExpansionStateVersion(staleUsers); - - for (let index = 0; index < 20; index += 1) { - const alternatePane = document.createElement("div"); - document.body.append(alternatePane); - render( - new ChatTranscriptController(host).render({ - ...props, - paneId: `alternate-pane-${index}`, - sessionKey: `alternate-session-${index}`, - }), - alternatePane, - ); - } - - render(controller.render(props), retainedPane); - const currentTools = getExpandedToolCards(sessionKey); - const currentUsers = getExpandedUserMessages(sessionKey); - expect(currentTools).not.toBe(staleTools); - expect(currentUsers).not.toBe(staleUsers); - expect(getExpansionStateVersion(currentTools)).toBe(previousToolVersion); - expect(getExpansionStateVersion(currentUsers)).toBe(previousUserVersion); - const toolCardId = expectDefined(currentTools.keys().next().value, "retained tool card"); - expectDefined( - retainedPane.querySelector( - ".chat-group.user .chat-message-disclosure__toggle", - ), - "mounted user disclosure", - ).click(); - expectDefined( - retainedPane.querySelector(".chat-tool-msg-summary"), - "mounted tool disclosure", - ).click(); - - expect(currentTools.get(toolCardId)).toBe(true); - expect(staleTools.get(toolCardId)).toBe(false); - expect(currentUsers.size).toBe(1); - expect(staleUsers.size).toBe(0); - - const toolVisibilitySession = "tool-visibility-session"; - const toolVisibilityProps = { - ...props, - paneId: "tool-visibility-pane", - sessionKey: toolVisibilitySession, - messages: [ - { role: "user", content: "tool visibility prompt", timestamp: 1 }, - { - role: "toolResult", - toolCallId: "expanded-tool", - toolName: "browser.open", - content: "Expanded tool result", - timestamp: 2, - }, - { role: "assistant", content: "The first tool completed.", timestamp: 3 }, - { role: "user", content: "Show the next tool result.", timestamp: 4 }, - { - role: "toolResult", - toolCallId: "collapsed-tool", - toolName: "browser.open", - content: "Collapsed tool result", - timestamp: 5, - }, - ], - }; - const toolVisibilityController = new ChatTranscriptController(host); - const toolVisibilityPane = document.createElement("div"); - document.body.append(toolVisibilityPane); - render(toolVisibilityController.render(toolVisibilityProps), toolVisibilityPane); - const visibilityState = getExpandedToolCards(toolVisibilitySession); - const visibilityIds = [...visibilityState.keys()].filter((key) => key.startsWith("toolmsg:")); - const expandedToolId = expectDefined(visibilityIds[0], "expanded standalone tool disclosure"); - const collapsedToolId = expectDefined( - visibilityIds[1], - "collapsed standalone tool disclosure", - ); - const disclosureButtons = () => - Array.from( - toolVisibilityPane.querySelectorAll(".chat-tool-msg-summary"), - ).filter((button) => !button.closest(".chat-tool-msg-body")); - expect(disclosureButtons()).toHaveLength(2); - expect(disclosureButtons().map((button) => button.getAttribute("aria-expanded"))).toEqual([ - "false", - "false", - ]); - expectDefined(disclosureButtons()[0], "first mounted tool disclosure").click(); - render(toolVisibilityController.render(toolVisibilityProps), toolVisibilityPane); - expectDefined(disclosureButtons()[1], "second mounted tool disclosure").click(); - render(toolVisibilityController.render(toolVisibilityProps), toolVisibilityPane); - expectDefined(disclosureButtons()[1], "second mounted tool disclosure").click(); - render(toolVisibilityController.render(toolVisibilityProps), toolVisibilityPane); - expect(disclosureButtons().map((button) => button.getAttribute("aria-expanded"))).toEqual([ - "true", - "false", - ]); - - render( - toolVisibilityController.render({ ...toolVisibilityProps, showToolCalls: false }), - toolVisibilityPane, - ); - expect(disclosureButtons()).toHaveLength(0); - render(toolVisibilityController.render(toolVisibilityProps), toolVisibilityPane); - - expect(disclosureButtons()).toHaveLength(2); - expect(disclosureButtons().map((button) => button.getAttribute("aria-expanded"))).toEqual([ - "true", - "false", - ]); - expect(visibilityState.get(expandedToolId)).toBe(true); - expect(visibilityState.get(collapsedToolId)).toBe(false); - render( - toolVisibilityController.render({ - ...toolVisibilityProps, - messages: toolVisibilityProps.messages.filter( - (message) => !("toolCallId" in message && message.toolCallId === "expanded-tool"), - ), - }), - toolVisibilityPane, - ); - expect(visibilityState.has(expandedToolId)).toBe(false); - expect(visibilityState.get(collapsedToolId)).toBe(false); - resetChatThreadPresentationState(); - } finally { - try { - if (environment) { - try { - document.body.replaceChildren(); - await new Promise((resolve) => { - window.setTimeout(resolve, 0); - }); - } finally { - await environment.teardown(globalThis); - } - } - } finally { - // Vitest assigns these compatibility globals after its own restore snapshot. - for (const [name, descriptor] of originalFixtureGlobals) { - if (descriptor) { - Object.defineProperty(globalThis, name, descriptor); - } else { - Reflect.deleteProperty(globalThis, name); - } - } - resetChatThreadState(); - } - } - - for (const [name, descriptor] of originalFixtureGlobals) { - expect(Object.getOwnPropertyDescriptor(globalThis, name)).toEqual(descriptor); - } - expect(Object.getOwnPropertyDescriptor(globalThis, "document")).toEqual(originalDocument); - expect(Object.getOwnPropertyDescriptor(globalThis, "window")).toEqual(originalWindow); - }); }); describe("user message expansion state", () => { diff --git a/ui/src/pages/chat/chat-view-state.ts b/ui/src/pages/chat/chat-view-state.ts index 5bc383d39c6a..d3143c890046 100644 --- a/ui/src/pages/chat/chat-view-state.ts +++ b/ui/src/pages/chat/chat-view-state.ts @@ -1,7 +1,7 @@ import { resetChatComposerState } from "./components/chat-composer.ts"; -import { resetChatThreadPresentationState } from "./components/chat-thread.ts"; +import { resetThreadPresentation } from "./components/chat-thread-interactions.ts"; export function resetChatViewState(paneId?: string, owner?: ParentNode) { resetChatComposerState(paneId); - resetChatThreadPresentationState(paneId, owner); + resetThreadPresentation(paneId, owner); } diff --git a/ui/src/pages/chat/chat-view.test-helpers.ts b/ui/src/pages/chat/chat-view.test-helpers.ts index 72a095f02164..24d9f776c997 100644 --- a/ui/src/pages/chat/chat-view.test-helpers.ts +++ b/ui/src/pages/chat/chat-view.test-helpers.ts @@ -1,6 +1,6 @@ import type { ReactiveControllerHost } from "lit"; import { vi } from "vitest"; -import { ChatTranscriptController } from "./components/chat-thread.ts"; +import { ChatTranscriptController } from "./components/chat-transcript-controller.ts"; export function createTestTranscript(): ChatTranscriptController { return new ChatTranscriptController({ diff --git a/ui/src/pages/chat/chat-view.test.ts b/ui/src/pages/chat/chat-view.test.ts index 27934d1638b1..6b77c2c95d7a 100644 --- a/ui/src/pages/chat/chat-view.test.ts +++ b/ui/src/pages/chat/chat-view.test.ts @@ -52,10 +52,10 @@ import * as chatMessage from "./components/chat-message.ts"; import { renderChatModelControls } from "./components/chat-model-controls.ts"; import { ChatSessionRailElement } from "./components/chat-session-rail.ts"; import { - resetChatThreadPresentationState, - resetChatThreadSessionPresentationState, - toggleChatThreadSearch, -} from "./components/chat-thread.ts"; + resetThreadPresentation, + resetTranscriptSession, + toggleTranscriptSearch, +} from "./components/chat-thread-interactions.ts"; import { renderWelcomeState } from "./components/chat-welcome.ts"; import { RealtimeTalkLevelSignal } from "./realtime-talk-level.ts"; import { @@ -2141,14 +2141,14 @@ describe("per-pane chat presentation state", () => { renderChatInto(container, { paneId, draft, getDraft: () => draft }); }; - toggleChatThreadSearch("pane-a", vi.fn()); + toggleTranscriptSearch("pane-a", vi.fn()); renderPane(paneA, "pane-a", ""); renderPane(paneB, "pane-b", ""); expect(paneA.querySelector(".agent-chat__search-bar")).not.toBeNull(); expect(paneB.querySelector(".agent-chat__search-bar")).toBeNull(); - toggleChatThreadSearch("pane-b", vi.fn()); - resetChatThreadSessionPresentationState("pane-a"); + toggleTranscriptSearch("pane-b", vi.fn()); + resetTranscriptSession("pane-a"); renderPane(paneA, "pane-a", ""); renderPane(paneB, "pane-b", ""); expect(paneA.querySelector(".agent-chat__search-bar")).toBeNull(); @@ -6848,11 +6848,11 @@ describe("right-click Reply", () => { .click(); flushFrames(); - resetChatThreadPresentationState("pane-b"); + resetThreadPresentation("pane-b"); expect(document.querySelector(".chat-reply-context-menu")).not.toBeNull(); expect(document.querySelector(".chat-confirm-popover")).not.toBeNull(); - resetChatThreadPresentationState("pane-a"); + resetThreadPresentation("pane-a"); expect(document.querySelector(".chat-reply-context-menu")).toBeNull(); expect(document.querySelector(".chat-confirm-popover")).toBeNull(); diff --git a/ui/src/pages/chat/chat-view.ts b/ui/src/pages/chat/chat-view.ts index 257e5acfd9b3..534e8f89da43 100644 --- a/ui/src/pages/chat/chat-view.ts +++ b/ui/src/pages/chat/chat-view.ts @@ -57,13 +57,13 @@ import type { SidebarContent, SidebarFullMessageLoader } from "./components/chat import { renderChatSwarmProgress } from "./components/chat-swarm-progress.ts"; import { renderChatTaskSuggestionTray } from "./components/chat-task-suggestions.ts"; import type { ChatTaskSuggestionTrayProps } from "./components/chat-task-suggestions.ts"; -import type { ChatReplyMessageAccess, ChatTranscriptController } from "./components/chat-thread.ts"; +import type { ReplyMessageAccess } from "./components/chat-thread-interactions.ts"; import { - renderChatPinnedMessages, - renderChatSearchBar, - renderChatThread, - toggleChatThreadSearch, -} from "./components/chat-thread.ts"; + renderTranscriptSearch, + toggleTranscriptSearch, +} from "./components/chat-thread-interactions.ts"; +import { renderChatThread } from "./components/chat-thread.ts"; +import type { ChatTranscriptController } from "./components/chat-transcript-controller.ts"; import type { ChatInputHistoryKeyInput, ChatInputHistoryKeyResult } from "./input-history.ts"; import type { RealtimeTalkConversationEntry } from "./realtime-talk-conversation.ts"; import type { RealtimeTalkCameraDevice } from "./realtime-talk-input.ts"; @@ -256,12 +256,11 @@ export type ChatProps = ChatTaskSuggestionTrayProps & onRevealWorkspaceFile?: (path: string) => void; onChatScroll?: (event: Event) => void; basePath?: string; - gatewayUrl?: string; composerControls?: TemplateResult | typeof nothing; replyTarget?: ChatReplyTarget | null; onClearReply?: () => void; onSetReply?: (target: ChatReplyTarget) => void; - replyMessageAccess?: ChatReplyMessageAccess; + replyMessageAccess?: ReplyMessageAccess; onRewindMessage?: (entryId: string) => Promise | boolean; onForkMessage?: (entryId: string) => Promise | void; sessionWorkspace?: SessionWorkspaceProps; @@ -348,7 +347,6 @@ export function renderChat(props: ChatProps) { questionPrompts: props.gatewayQuestionPrompts, sessions: props.sessions, sessionHost: props.sessionHost, - gatewayUrl: props.gatewayUrl, boardProvider: props.boardProvider, assistantName: props.assistantName, assistantAvatar: props.assistantAvatar, @@ -422,7 +420,6 @@ export function renderChat(props: ChatProps) { persistCommentary: props.persistCommentary, sessions: props.sessions, sessionHost: props.sessionHost, - gatewayUrl: props.gatewayUrl, assistantName: props.assistantName, assistantAvatar: props.assistantAvatar, assistantAvatarUrl: props.assistantAvatarUrl, @@ -582,21 +579,11 @@ export function renderChat(props: ChatProps) { resolveAsciiShortcutKey(event) === "f" ) { event.preventDefault(); - toggleChatThreadSearch(props.paneId, requestUpdate, event); + toggleTranscriptSearch(props.paneId, requestUpdate, event); } }} > - ${renderChatViewNotices(props)} ${renderChatSearchBar(props.paneId, requestUpdate)} - ${renderChatPinnedMessages( - { - paneId: props.paneId, - sessionKey: props.sessionKey, - messages: props.messages, - userName: props.userName, - userAvatar: props.userAvatar, - }, - requestUpdate, - )} + ${renderChatViewNotices(props)} ${renderTranscriptSearch(props.paneId, requestUpdate)}
void; + onOpenReply?: (replyToId: string) => void; + }; +}; + +export type ReplyMessageAccess = { + revision: number; + navigationId: string | null; + read: (messageId: string) => unknown; + request: (messageId: string) => void; + open: (messageId: string) => void; +}; + +export type ChatThreadProps = { + paneId: string; + sessionKey: string; + boardProvider?: BoardProvider; + announceTranscript?: boolean; + loading: boolean; + historyPagination?: { loading: boolean }; + messages: unknown[]; + toolMessages: unknown[]; + streamSegments: ChatStreamSegment[]; + stream: string | null; + streamStartedAt: number | null; + runId?: string | null; + runOutputTokens?: number | null; + queue: ChatQueueItem[]; + showThinking: boolean; + showToolCalls: boolean; + persistCommentary?: boolean; + runActive?: boolean; + runWorking?: boolean; + startupStatus?: ChatRunStartupStatus | null; + waitingApproval?: boolean; + planStatus?: PlanStatus | null; + questionPrompts?: readonly QuestionPrompt[]; + sessions: SessionsListResult | null; + sessionHost?: UiSessionDefaultsHost | null; + assistantName: string; + assistantAvatar: string | null; + assistantAvatarUrl?: string | null; + userId?: string | null; + userName?: string | null; + userAvatar?: string | null; + basePath?: string; + fullMessageAgentId?: string; + loadFullAssistantMessage?: SidebarFullMessageLoader | null; + localMediaPreviewRoots?: string[]; + assistantAttachmentAuthToken?: string | null; + resolveArtifactDownload?: ArtifactDownloadResolver; + canvasPluginSurfaceUrl?: string | null; + embedSandboxMode?: EmbedSandboxMode; + allowExternalEmbedUrls?: boolean; + autoExpandToolCalls?: boolean; + realtimeTalkConversation?: RealtimeTalkConversationEntry[]; + onOpenSidebar?: (content: SidebarContent) => void; + onOpenWorkspaceFile?: (target: { path: string; line?: number | null }) => void; + onOpenSessionCheckpoints?: () => void | Promise; + onAssistantAttachmentLoaded?: () => void; + onRequestOpenImage?: () => number; + onOpenImage?: (item: ImageLightboxItem, requestVersion?: number) => void; + onRequestUpdate?: () => void; + onChatScroll?: (event: Event) => void; + onHistoryIntent?: (event: Event) => void; + onDraftChange: (next: string) => void; + onSend: () => void; + onSetReply?: (target: MessageReplyTarget) => void; + replyMessageAccess?: ReplyMessageAccess; + onRewindMessage?: (entryId: string) => Promise | boolean; + onForkMessage?: (entryId: string) => Promise | void; + onFocusComposer?: () => void; + onCompanionQuestion?: (question: string) => void; + onCompanionPrefill?: (question: string) => void; + onOpenSession?: (sessionKey: string) => void; + modelSetupRequired?: boolean; + onModelSetup?: () => void; + backgroundTasks?: BackgroundTasksProps; +}; + +type TranscriptInteractionProps = Pick< + ChatThreadProps, + | "paneId" + | "runActive" + | "runWorking" + | "onSetReply" + | "onRewindMessage" + | "onForkMessage" + | "onFocusComposer" + | "onCompanionQuestion" + | "onCompanionPrefill" +>; + +function createTranscriptState(): ChatThreadState { + return { + searchOpen: false, + searchQuery: "", + searchFocusPending: false, + searchReturnFocusTarget: null, + searchReturnFocusOwner: null, + transcriptRenderDependencies: [], + transcriptRenderContext: {}, + }; +} + +const transcriptStates = new Map(); + +export function getTranscriptState(paneId: string): ChatThreadState { + const existing = transcriptStates.get(paneId); + if (existing) { + return existing; + } + const state = createTranscriptState(); + transcriptStates.set(paneId, state); + return state; +} + +function dismissThreadPortals(paneId?: string, owner?: ParentNode): void { + removeReplyContextMenu(paneId); + if (owner) { + dismissConfirmedActionPopovers(owner); + } + // The selection popup is body-portaled; pane teardown/route changes must + // drop it so it cannot outlive the render that owns its callbacks. + removeChatSelectionPopup(); +} + +export function resetTranscriptSession(paneId: string, owner?: ParentNode): void { + dismissThreadPortals(paneId, owner); + const state = transcriptStates.get(paneId); + if (state) { + // Search input belongs to the outgoing transcript. Other fields are pane + // preferences or dependency memos and invalidate themselves on new props. + state.searchOpen = false; + state.searchQuery = ""; + state.searchFocusPending = false; + state.searchReturnFocusTarget = null; + state.searchReturnFocusOwner = null; + } +} + +export function resetThreadPresentation(paneId?: string, owner?: ParentNode) { + dismissThreadPortals(paneId, owner); + if (paneId) { + transcriptStates.delete(paneId); + resetChatThreadState(paneId); + } else { + transcriptStates.clear(); + resetChatThreadState(); + } +} + +export function renderTranscriptSearch( + paneId: string, + requestUpdate: () => void, +): TemplateResult | typeof nothing { + const state = getTranscriptState(paneId); + if (!state.searchOpen) { + return nothing; + } + return html` +
+ ${icons.search} + { + if (element instanceof HTMLInputElement) { + state.searchFocusPending = false; + queueMicrotask(() => { + if (element.isConnected) { + element.focus({ preventScroll: true }); + } + }); + } + }) + : nothing} + @input=${(event: Event) => { + state.searchQuery = (event.target as HTMLInputElement).value; + requestUpdate(); + }} + /> + + + +
+ `; +} + +export function closeTranscriptSearch(state: ChatThreadState, requestUpdate: () => void): void { + const returnFocusTarget = state.searchReturnFocusTarget; + const returnFocusOwner = state.searchReturnFocusOwner; + state.searchOpen = false; + state.searchQuery = ""; + state.searchFocusPending = false; + state.searchReturnFocusTarget = null; + state.searchReturnFocusOwner = null; + requestUpdate(); + queueMicrotask(() => { + const target = returnFocusTarget?.isConnected + ? returnFocusTarget + : returnFocusOwner?.querySelector( + ".agent-chat__composer-combobox > textarea", + ); + target?.focus({ preventScroll: true }); + }); +} + +/** Toggles transcript search and retains the shortcut origin for focus restoration. */ +export function toggleTranscriptSearch( + paneId: string, + requestUpdate: () => void, + triggerEvent?: Event, +): void { + const state = getTranscriptState(paneId); + if (state.searchOpen) { + closeTranscriptSearch(state, requestUpdate); + return; + } + + state.searchOpen = true; + state.searchFocusPending = true; + const returnFocusTarget = triggerEvent?.target; + const returnFocusOwner = triggerEvent?.currentTarget; + state.searchReturnFocusTarget = + returnFocusTarget instanceof HTMLElement && returnFocusTarget.isConnected + ? returnFocusTarget + : null; + state.searchReturnFocusOwner = + returnFocusOwner instanceof HTMLElement && returnFocusOwner.isConnected + ? returnFocusOwner + : null; + requestUpdate(); +} + +let activeReplyContextMenu: HTMLElement | null = null; +let activeReplyContextMenuPaneId: string | null = null; +let contextMenuDocumentClickHandler: ((event: MouseEvent) => void) | null = null; +let contextMenuDocumentContextMenuHandler: ((event: MouseEvent) => void) | null = null; +let contextMenuKeydownHandler: ((event: KeyboardEvent) => void) | null = null; + +function removeReplyContextMenu(paneId?: string) { + if (paneId && paneId !== activeReplyContextMenuPaneId) { + return; + } + if (activeReplyContextMenu) { + dismissConfirmedActionPopovers(activeReplyContextMenu); + activeReplyContextMenu.remove(); + } + activeReplyContextMenu = null; + activeReplyContextMenuPaneId = null; + const fallbackMenu = document.querySelector(".chat-reply-context-menu"); + if (fallbackMenu) { + dismissConfirmedActionPopovers(fallbackMenu); + fallbackMenu.remove(); + } + if (contextMenuDocumentClickHandler) { + document.removeEventListener("click", contextMenuDocumentClickHandler); + contextMenuDocumentClickHandler = null; + } + if (contextMenuDocumentContextMenuHandler) { + document.removeEventListener("contextmenu", contextMenuDocumentContextMenuHandler, true); + contextMenuDocumentContextMenuHandler = null; + } + if (contextMenuKeydownHandler) { + document.removeEventListener("keydown", contextMenuKeydownHandler); + contextMenuKeydownHandler = null; + } +} + +function stableReplyMessageId(senderLabel: string | undefined, text: string): string { + const source = `${senderLabel ?? ""}\n${text}`; + return `reply:${fnv1aUtf16(source).toString(16)}`; +} + +function createReplyContextMenuButton(onClick: () => void): HTMLButtonElement { + const button = document.createElement("button"); + button.type = "button"; + button.setAttribute("role", "menuitem"); + button.setAttribute("aria-label", t("chat.messages.replyToMessage")); + button.textContent = t("chat.messages.reply"); + button.addEventListener("click", onClick); + return button; +} + +function createMessageActionContextButton(params: { + label: string; + disabled: boolean; + tooltip: string; + onClick: () => void; +}): { element: HTMLElement; button: HTMLButtonElement } { + const button = document.createElement("button"); + button.type = "button"; + button.disabled = params.disabled; + button.setAttribute("role", "menuitem"); + button.setAttribute("aria-label", params.label); + button.textContent = params.label; + button.addEventListener("click", params.onClick); + const tooltip = document.createElement("openclaw-tooltip"); + tooltip.content = params.tooltip; + tooltip.append(button); + return { element: tooltip, button }; +} + +export function handleTranscriptSelection(event: PointerEvent, props: TranscriptInteractionProps) { + if ( + typeof props.onCompanionQuestion !== "function" || + typeof props.onCompanionPrefill !== "function" + ) { + return; + } + handleChatSelectionPointerUp(event, { + onMoreDetails: (selection) => { + const question = buildMoreDetailsCompanionQuestion(selection); + if (question) { + props.onCompanionQuestion?.(question); + } + }, + onAskSideChat: (selection) => { + const question = buildCompanionQuestionPrefill(selection); + if (question) { + props.onCompanionPrefill?.(question); + } + }, + }); +} + +function selectionIntersectsElement(selection: Selection | null, element: Element): boolean { + if (!selection || selection.isCollapsed) { + return false; + } + for (let index = 0; index < selection.rangeCount; index += 1) { + if (selection.getRangeAt(index).intersectsNode(element)) { + return true; + } + } + return false; +} + +export function handleTranscriptContextMenu(event: MouseEvent, props: TranscriptInteractionProps) { + if (event.composedPath().some((target) => target instanceof HTMLAnchorElement)) { + return; + } + const bubble = (event.target as HTMLElement).closest(".chat-bubble"); + if (!bubble) { + return; + } + const group = bubble.closest(".chat-group"); + if (!group) { + return; + } + if ( + group.querySelector(".chat-reading-indicator") || + group.querySelector(".chat-bubble.streaming") + ) { + return; + } + const senderEl = group.querySelector(".chat-sender-name"); + const senderLabel = senderEl?.textContent?.trim() ?? undefined; + const text = truncateUtf16Safe((bubble as HTMLElement).dataset.messageText?.trim() ?? "", 500); + const entryId = (bubble as HTMLElement).dataset.entryId?.trim() ?? ""; + const messageId = (bubble as HTMLElement).dataset.messageId?.trim() ?? ""; + const isUserMessage = group.classList.contains("user") && Boolean(entryId); + // Grouped rows can contain several bubbles. Match the clicked bubble to its + // own action owner so copy never targets a sibling message. + const actionOwner = [...group.querySelectorAll("[data-message-actions-for]")].find( + (element) => element.dataset.messageActionsFor === messageId, + ); + const copyButton = actionOwner?.querySelector(".chat-copy-btn"); + const canReply = Boolean(text && props.onSetReply); + const canRewind = isUserMessage && typeof props.onRewindMessage === "function"; + const canCopy = Boolean(copyButton); + const canFork = isUserMessage && typeof props.onForkMessage === "function"; + if (!canReply && !canRewind && !canCopy && !canFork) { + return; + } + + const selection = window.getSelection(); + const selectedText = selectionIntersectsElement(selection, bubble) ? selection?.toString() : ""; + + event.preventDefault(); + event.stopPropagation(); + removeReplyContextMenu(); + const menu = document.createElement("div"); + menu.className = "chat-reply-context-menu"; + menu.setAttribute("role", "menu"); + menu.setAttribute("aria-label", t("chat.messages.actions")); + menu.style.left = `${event.clientX}px`; + menu.style.top = `${event.clientY}px`; + const focusCandidates: HTMLButtonElement[] = []; + if (selectedText) { + const action = createMessageActionContextButton({ + label: t("chat.messages.copySelection"), + disabled: false, + tooltip: t("chat.messages.copySelection"), + onClick: () => { + void copyToClipboard(selectedText); + removeReplyContextMenu(); + }, + }); + menu.append(action.element); + focusCandidates.push(action.button); + } + if (canReply) { + const replyMessageId = messageId || stableReplyMessageId(senderLabel, text); + const replyButton = createReplyContextMenuButton(() => { + props.onSetReply?.({ + messageId: replyMessageId, + text, + senderLabel, + ...(entryId ? { sourceMessageId: entryId } : {}), + }); + removeReplyContextMenu(); + props.onFocusComposer?.(); + }); + menu.append(replyButton); + focusCandidates.push(replyButton); + } + const working = Boolean(props.runActive || props.runWorking); + if (canRewind) { + const action = createMessageActionContextButton({ + label: t("chat.messages.rewindToHere"), + disabled: working, + tooltip: working ? t("chat.messages.rewindUnavailable") : t("chat.messages.rewindToHere"), + onClick: () => { + openChatRewindConfirmation(action.button, () => { + removeReplyContextMenu(); + void Promise.resolve(props.onRewindMessage?.(entryId)).then((rewound) => { + if (rewound) { + props.onFocusComposer?.(); + } + }); + }); + }, + }); + action.element.classList.add("chat-confirm-wrap", "chat-rewind-wrap"); + menu.append(action.element); + focusCandidates.push(action.button); + } + if (canCopy) { + const action = createMessageActionContextButton({ + label: copyMarkdownLabel(), + disabled: false, + tooltip: copyMarkdownLabel(), + onClick: () => { + removeReplyContextMenu(); + copyButton?.click(); + }, + }); + menu.append(action.element); + focusCandidates.push(action.button); + } + if (canFork) { + const action = createMessageActionContextButton({ + label: t("chat.messages.forkFromHere"), + disabled: working, + tooltip: working ? t("chat.messages.forkUnavailable") : t("chat.messages.forkFromHere"), + onClick: () => { + removeReplyContextMenu(); + void props.onForkMessage?.(entryId); + }, + }); + menu.append(action.element); + focusCandidates.push(action.button); + } + document.body.appendChild(menu); + activeReplyContextMenu = menu; + activeReplyContextMenuPaneId = props.paneId; + + const menuRect = menu.getBoundingClientRect(); + let left = event.clientX; + let top = event.clientY; + if (left + menuRect.width > window.innerWidth) { + left = window.innerWidth - menuRect.width - 8; + } + if (top + menuRect.height > window.innerHeight) { + top = window.innerHeight - menuRect.height - 8; + } + menu.style.left = `${Math.max(0, left)}px`; + menu.style.top = `${Math.max(0, top)}px`; + focusCandidates.find((button) => !button.disabled)?.focus(); + requestAnimationFrame(() => { + if (!menu.isConnected || activeReplyContextMenu !== menu) { + return; + } + contextMenuDocumentClickHandler = (nextEvent: MouseEvent) => { + if (!menu.contains(nextEvent.target as Node | null)) { + removeReplyContextMenu(); + } + }; + contextMenuDocumentContextMenuHandler = (nextEvent: MouseEvent) => { + if (!menu.contains(nextEvent.target as Node | null)) { + removeReplyContextMenu(); + } + }; + const handleKeydown = (nextEvent: KeyboardEvent) => { + if (nextEvent.key === "Escape") { + nextEvent.preventDefault(); + nextEvent.stopPropagation(); + removeReplyContextMenu(); + props.onFocusComposer?.(); + } + }; + contextMenuKeydownHandler = handleKeydown; + document.addEventListener("click", contextMenuDocumentClickHandler); + // Capture closes this owner even when the next menu stops event propagation. + document.addEventListener("contextmenu", contextMenuDocumentContextMenuHandler, true); + document.addEventListener("keydown", handleKeydown); + }); +} diff --git a/ui/src/pages/chat/components/chat-thread.measure.test.ts b/ui/src/pages/chat/components/chat-thread.measure.test.ts deleted file mode 100644 index ccf2d51c3e31..000000000000 --- a/ui/src/pages/chat/components/chat-thread.measure.test.ts +++ /dev/null @@ -1,909 +0,0 @@ -/* @vitest-environment jsdom */ - -// Regression: re-stamping the transcript into a new container (the -// chat<->dashboard face switch) must keep every rendered row observed for -// size changes. A synchronous measureElement(null) prune during the commit -// unobserved just-registered sibling rows, freezing their heights at the old -// pane width and overlapping the bubbles in the dashboard chat dock. -import { render } from "lit"; -import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import type { BoardProvider } from "../../../lib/board/provider.ts"; -import { resolveAssistantAttachmentAuthToken } from "../chat-pane-state.ts"; -import { createTestChatPane } from "../chat-pane.test-support.ts"; -import * as chatThreadBuild from "../chat-thread-build.ts"; -import { buildCachedChatItems, resetChatThreadState } from "../chat-thread.ts"; -import { createTestTranscript } from "../chat-view.test-helpers.ts"; -import { - isChatMediaResourceCurrent, - observeChatMediaResource, - releaseChatMediaResourceSubscriber, -} from "./chat-message-media.ts"; -import { - renderChatThread, - renderChatSearchBar, - resetChatThreadPresentationState, - resetChatThreadSessionPresentationState, - toggleChatThreadSearch, -} from "./chat-thread.ts"; - -const observedElements = new Set(); -const resizeObservers = new Set(); -let measuredRowHeight = 100; - -class RecordingResizeObserver implements ResizeObserver { - private readonly targets = new Set(); - constructor(private readonly callback: ResizeObserverCallback) { - resizeObservers.add(this); - } - observe(target: Element): void { - this.targets.add(target); - observedElements.add(target); - } - unobserve(target: Element): void { - this.targets.delete(target); - observedElements.delete(target); - } - disconnect(): void { - for (const target of this.targets) { - observedElements.delete(target); - } - this.targets.clear(); - resizeObservers.delete(this); - } - emit(width: number, height: number): void { - const entries = [...this.targets].map( - (target) => - ({ - target, - borderBoxSize: [{ inlineSize: width, blockSize: height }], - }) as unknown as ResizeObserverEntry, - ); - if (entries.length > 0) { - this.callback(entries, this); - } - } - - observes(target: Element): boolean { - return this.targets.has(target); - } -} - -const defaultMessages = [ - { role: "user", content: "message one", timestamp: 1_000 }, - { role: "assistant", content: "reply one", timestamp: 2_000 }, - { role: "user", content: "message two", timestamp: 3_000 }, - { role: "assistant", content: "reply two", timestamp: 4_000 }, -]; - -function threadProps( - paneId: string, - sessionKey = "agent:main:main", - messages: unknown[] = defaultMessages, -) { - return { - paneId, - sessionKey, - loading: false, - messages, - toolMessages: [], - streamSegments: [], - stream: null, - streamStartedAt: null, - queue: [], - showThinking: false, - showToolCalls: false, - sessions: null, - assistantName: "Molty", - assistantAvatar: null, - onDraftChange: () => {}, - onSend: () => {}, - }; -} - -function transcriptRows(container: HTMLElement): HTMLElement[] { - return [...container.querySelectorAll(".chat-virtual-row")]; -} - -async function flushDeferredRowPrune(): Promise { - await new Promise((resolve) => { - setTimeout(resolve, 0); - }); -} - -describe("chat transcript row measurement", () => { - beforeEach(() => { - observedElements.clear(); - resizeObservers.clear(); - measuredRowHeight = 100; - vi.stubGlobal("ResizeObserver", RecordingResizeObserver); - // jsdom reports 0x0 rects and offsetHeight 0; keep the virtualizer - // viewport and measured row sizes non-zero so re-renders keep producing - // virtual rows. - vi.spyOn(HTMLElement.prototype, "offsetHeight", "get").mockImplementation( - () => measuredRowHeight, - ); - vi.spyOn(Element.prototype, "getBoundingClientRect").mockReturnValue({ - x: 0, - y: 0, - top: 0, - left: 0, - right: 800, - bottom: 600, - width: 800, - height: 600, - toJSON: () => ({}), - } as DOMRect); - }); - - afterEach(() => { - vi.restoreAllMocks(); - vi.unstubAllGlobals(); - resetChatThreadPresentationState(); - resetChatThreadState(); - document.body.replaceChildren(); - }); - - it("keeps every re-stamped row observed after moving containers", async () => { - const transcript = createTestTranscript(); - const props = threadProps("pane-measure"); - const chatFace = document.body.appendChild(document.createElement("div")); - render(renderChatThread(props, transcript), chatFace); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const chatRows = transcriptRows(chatFace); - expect(chatRows.length).toBeGreaterThanOrEqual(4); - for (const row of chatRows) { - expect(observedElements.has(row)).toBe(true); - } - - // Re-stamp the same session transcript into a new container while the old - // tree is still tracked, mirroring the dashboard face-switch commit. - const dashboardDock = document.body.appendChild(document.createElement("div")); - render(renderChatThread(props, transcript), dashboardDock); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const dockRows = transcriptRows(dashboardDock); - expect(dockRows.length).toBe(chatRows.length); - for (const row of dockRows) { - expect(observedElements.has(row)).toBe(true); - } - for (const row of chatRows) { - expect(observedElements.has(row)).toBe(false); - } - }); - - it("resolves persisted replies to their source and highlights it on click", async () => { - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const props = threadProps("pane-reply-preview", "agent:main:main", [ - { - role: "assistant", - content: "The original answer", - __openclaw: { id: "source-message" }, - timestamp: 1_000, - }, - { - role: "user", - content: "Follow up", - __openclaw: { id: "reply-message", replyToId: "source-message" }, - timestamp: 2_000, - }, - ]); - render(renderChatThread(props, transcript), container); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const preview = container.querySelector(".chat-reply-preview--message"); - expect(preview?.textContent).toContain("Replying to Molty"); - expect(preview?.textContent).toContain("The original answer"); - expect(preview?.textContent).not.toContain("source-message"); - - preview?.click(); - await Promise.resolve(); - - const sourceBubble = [...container.querySelectorAll(".chat-bubble")].find( - (bubble) => bubble.dataset.entryId === "source-message", - ); - expect(sourceBubble?.classList.contains("chat-bubble--reply-target")).toBe(true); - transcript.hostDisconnected(); - }); - - it("hydrates an unloaded reply preview without inserting its source row", async () => { - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - let resolvedMessage: unknown = undefined; - const request = vi.fn(); - const open = vi.fn(); - const props = { - ...threadProps("pane-reply-hydration", "agent:main:main", [ - { - role: "user", - content: "Follow up", - __openclaw: { id: "reply-message", replyToId: "source-message" }, - timestamp: 2_000, - }, - ]), - replyMessageAccess: { - revision: 0, - navigationId: null, - read: () => resolvedMessage, - request, - open, - }, - }; - const rerender = () => { - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - }; - rerender(); - transcript.hostConnected(); - await flushDeferredRowPrune(); - - expect(request).toHaveBeenCalledWith("source-message"); - expect(container.querySelector("[data-entry-id='source-message']")).toBeNull(); - - resolvedMessage = { - role: "assistant", - content: "The original answer", - __openclaw: { id: "source-message" }, - timestamp: 1_000, - }; - props.replyMessageAccess.revision += 1; - rerender(); - - const preview = container.querySelector(".chat-reply-preview--message"); - expect(preview?.textContent).toContain("Replying to Molty"); - expect(preview?.textContent).toContain("The original answer"); - preview?.click(); - expect(open).toHaveBeenCalledWith("source-message"); - transcript.hostDisconnected(); - }); - - it("clears search before navigating to a filtered reply target", async () => { - const transcript = createTestTranscript(); - const searchContainer = document.body.appendChild(document.createElement("div")); - const threadContainer = document.body.appendChild(document.createElement("div")); - const open = vi.fn(); - const paneId = "pane-filtered-reply-navigation"; - const props = { - ...threadProps(paneId, "agent:main:main", [ - { - role: "assistant", - content: "The original answer", - __openclaw: { id: "source-message" }, - timestamp: 1_000, - }, - { - role: "user", - content: "Follow up", - __openclaw: { - id: "reply-message", - replyToId: "source-message", - replyToPreview: { text: "The original answer", senderLabel: "Molty" }, - }, - timestamp: 2_000, - }, - ]), - replyMessageAccess: { - revision: 0, - navigationId: null, - read: () => undefined, - request: vi.fn(), - open, - }, - }; - const rerender = () => { - render(renderChatSearchBar(paneId, rerender), searchContainer); - render( - renderChatThread({ ...props, onRequestUpdate: rerender }, transcript), - threadContainer, - ); - transcript.hostUpdated(); - }; - toggleChatThreadSearch(paneId, rerender); - rerender(); - transcript.hostConnected(); - const input = searchContainer.querySelector("input"); - expect(input).not.toBeNull(); - input!.value = "Follow up"; - input!.dispatchEvent(new Event("input", { bubbles: true })); - await flushDeferredRowPrune(); - - expect(threadContainer.querySelector("[data-entry-id='source-message']")).toBeNull(); - const preview = threadContainer.querySelector( - ".chat-reply-preview--message", - ); - expect(preview).not.toBeNull(); - preview!.click(); - - expect(open).toHaveBeenCalledWith("source-message"); - expect(searchContainer.querySelector("input")).toBeNull(); - transcript.hostDisconnected(); - }); - - it("loads a truncated assistant message once and keeps the full text visible", async () => { - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const loadFullAssistantMessage = vi.fn().mockResolvedValue({ - ok: true, - message: { role: "assistant", content: "Complete assistant content." }, - }); - function rerender() { - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - } - const props = { - ...threadProps("pane-assistant-expand", "agent:work:main", [ - { - role: "assistant", - content: "Preview\n...(truncated)...", - __openclaw: { id: "assistant-full-1" }, - timestamp: 1_000, - }, - ]), - fullMessageAgentId: "work", - loadFullAssistantMessage, - onRequestUpdate: rerender, - }; - rerender(); - transcript.hostConnected(); - transcript.hostUpdated(); - - await vi.waitFor(() => expect(container.textContent).toContain("Complete assistant content.")); - expect(loadFullAssistantMessage).toHaveBeenCalledOnce(); - expect(loadFullAssistantMessage).toHaveBeenCalledWith({ - sessionKey: "agent:work:main", - agentId: "work", - messageId: "assistant-full-1", - kind: "assistant_message", - }); - - expect(container.querySelector(".chat-message-disclosure__toggle")).toBeNull(); - expect(container.textContent).toContain("Complete assistant content."); - expect(loadFullAssistantMessage).toHaveBeenCalledOnce(); - transcript.hostDisconnected(); - }); - - it("keeps transport-cut assistant text as received when full content is unavailable", async () => { - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const loadFullAssistantMessage = vi.fn().mockRejectedValue(new Error("offline")); - function rerender() { - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - } - const props = { - ...threadProps("pane-assistant-retry", "agent:main:main", [ - { - role: "assistant", - content: "Preview\n...(truncated)...", - __openclaw: { id: "assistant-retry-1" }, - timestamp: 1_000, - }, - ]), - loadFullAssistantMessage, - onRequestUpdate: rerender, - }; - rerender(); - transcript.hostConnected(); - transcript.hostUpdated(); - - await vi.waitFor(() => expect(loadFullAssistantMessage).toHaveBeenCalledOnce()); - expect(container.textContent).toContain("Preview"); - expect(container.textContent).toContain("...(truncated)..."); - expect(container.querySelector(".chat-message-disclosure__toggle")).toBeNull(); - transcript.hostDisconnected(); - }); - - it.each(["Enter", " "])("opens focused transcript file links with %j", async (key) => { - const transcript = createTestTranscript(); - const onOpenWorkspaceFile = vi.fn(); - const onHistoryIntent = vi.fn(); - const container = document.body.appendChild(document.createElement("div")); - const props = { - ...threadProps("pane-file-link", "agent:main:main", [ - { role: "assistant", content: "Inspect `src/chat.ts:17`", timestamp: 1_000 }, - ]), - onOpenWorkspaceFile, - onHistoryIntent, - }; - render(renderChatThread(props, transcript), container); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const link = container.querySelector("a.markdown-file-link"); - link?.focus(); - expect(document.activeElement).toBe(link); - const event = new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }); - link?.dispatchEvent(event); - - expect(event.defaultPrevented).toBe(true); - expect(onOpenWorkspaceFile).toHaveBeenCalledWith({ path: "src/chat.ts", line: 17 }); - expect(onHistoryIntent).not.toHaveBeenCalled(); - transcript.hostDisconnected(); - }); - - it("keeps built row identities across an A to B to A presentation reset", () => { - const paneId = "pane-session-items"; - const messagesA = [{ role: "assistant", content: "session A", timestamp: 1_000 }]; - const messagesB = [{ role: "assistant", content: "session B", timestamp: 2_000 }]; - const stableInputs = { - paneId, - runId: null, - toolMessages: [], - streamSegments: [], - stream: null, - streamStartedAt: null, - showToolCalls: true, - }; - const buildSpy = vi.spyOn(chatThreadBuild, "buildChatItems"); - const itemsA = buildCachedChatItems({ - ...stableInputs, - sessionKey: "agent:main:session-a", - messages: messagesA, - }); - - resetChatThreadSessionPresentationState(paneId); - buildCachedChatItems({ - ...stableInputs, - sessionKey: "agent:main:session-b", - messages: messagesB, - }); - resetChatThreadSessionPresentationState(paneId); - const restoredItemsA = buildCachedChatItems({ - ...stableInputs, - sessionKey: "agent:main:session-a", - messages: messagesA, - }); - - expect(buildSpy).toHaveBeenCalledTimes(2); - expect(restoredItemsA).toBe(itemsA); - expect(restoredItemsA.every((item, index) => item === itemsA[index])).toBe(true); - }); - - it("pauses an unmeasurable restore until loading commits an empty transcript", () => { - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const props = threadProps("pane-loading-scroll", "agent:main:session-a", []); - render(renderChatThread({ ...props, loading: true }, transcript), container); - transcript.hostConnected(); - transcript.hostUpdated(); - transcript.scrollToOffset(420); - transcript.hostUpdated(); - - expect(transcript.pendingScrollOffsetFor(props.sessionKey)).toBe(420); - - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - expect(transcript.pendingScrollOffsetFor(props.sessionKey)).toBeNull(); - }); - - it("settles a restored offset when loaded rows no longer overflow", () => { - const frames: FrameRequestCallback[] = []; - vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => { - frames.push(callback); - return frames.length; - }); - vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => undefined); - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const props = threadProps("pane-short-scroll", "agent:main:session-a"); - render(renderChatThread(props, transcript), container); - transcript.hostConnected(); - transcript.hostUpdated(); - transcript.scrollToOffset(420); - - for (let index = 0; index <= 60; index += 1) { - transcript.hostUpdated(); - for (const frame of frames.splice(0)) { - frame(0); - } - } - - expect(transcript.pendingScrollOffsetFor(props.sessionKey)).toBeNull(); - }); - - it("updates rendered row offsets from freshly wrapped heights while scrolling", async () => { - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const props = threadProps("pane-width-remeasure"); - const renderTranscript = async () => { - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - }; - - await renderTranscript(); - transcript.hostConnected(); - await renderTranscript(); - expect(transcriptRows(container)[1]?.style.transform).toBe("translateY(100px)"); - - const scrollElement = container.querySelector(".chat-thread"); - expect(scrollElement).not.toBeNull(); - scrollElement!.scrollTop = 40; - scrollElement!.dispatchEvent(new Event("scroll")); - const virtualizer = ( - transcript as unknown as { - sessionVirtualizer: { - virtualizerController: { getVirtualizer: () => { isScrolling: boolean } }; - }; - } - ).sessionVirtualizer.virtualizerController.getVirtualizer(); - expect(virtualizer.isScrolling).toBe(true); - - measuredRowHeight = 180; - for (const observer of resizeObservers) { - if (scrollElement && observer.observes(scrollElement)) { - observer.emit(640, 600); - } - } - await renderTranscript(); - - expect(transcriptRows(container)[1]?.style.transform).toBe("translateY(180px)"); - transcript.hostDisconnected(); - }); - - it.each([ - { label: "end-pinned", distanceFromEnd: 0, expectedCalls: 1 }, - { label: "scrolled away", distanceFromEnd: 100, expectedCalls: 0 }, - ])( - "$label transcript preserves its resize anchor", - async ({ distanceFromEnd, expectedCalls }) => { - measuredRowHeight = 240; - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const messages = Array.from({ length: 12 }, (_, index) => ({ - role: index % 2 === 0 ? "user" : "assistant", - content: `message ${index}`, - timestamp: index + 1, - })); - const props = threadProps( - `pane-height-resize-${distanceFromEnd}`, - "agent:main:resize", - messages, - ); - render(renderChatThread(props, transcript), container); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const scrollElement = container.querySelector(".chat-thread"); - expect(scrollElement).not.toBeNull(); - const virtualizer = ( - transcript as unknown as { - sessionVirtualizer: { - virtualizerController: { - getVirtualizer: () => { - scrollOffset: number | null; - getTotalSize: () => number; - scrollToEnd: (options?: { behavior?: ScrollBehavior }) => void; - }; - }; - }; - } - ).sessionVirtualizer.virtualizerController.getVirtualizer(); - const scrollToEnd = vi.spyOn(virtualizer, "scrollToEnd"); - const emitViewportResize = (height: number) => { - for (const observer of resizeObservers) { - if (scrollElement && observer.observes(scrollElement)) { - observer.emit(800, height); - } - } - }; - - emitViewportResize(600); - scrollToEnd.mockClear(); - expect(virtualizer.getTotalSize()).toBeGreaterThan(700); - virtualizer.scrollOffset = Math.max(0, virtualizer.getTotalSize() - 600 - distanceFromEnd); - emitViewportResize(560); - - expect(scrollToEnd).toHaveBeenCalledTimes(expectedCalls); - if (expectedCalls > 0) { - expect(scrollToEnd).toHaveBeenCalledWith({ behavior: "auto" }); - } - transcript.hostDisconnected(); - }, - ); - - it("rebinds guarded transcript images when the gateway rotates its auth token", async () => { - const NativeUrl = URL; - const blobUrl = `blob:transcript-media-${crypto.randomUUID()}`; - vi.stubGlobal( - "URL", - class extends NativeUrl { - static override createObjectURL = vi.fn(() => blobUrl); - static override revokeObjectURL = vi.fn(); - }, - ); - - let previousSignal: AbortSignal | undefined; - const fetchMock = vi.fn((_source: string, init?: RequestInit) => { - if (fetchMock.mock.calls.length === 1) { - return new Promise((_resolve, reject) => { - previousSignal = init?.signal ?? undefined; - previousSignal?.addEventListener( - "abort", - () => reject(new DOMException("media scope changed", "AbortError")), - { once: true }, - ); - }); - } - return Promise.resolve({ - ok: true, - blob: async () => new Blob(["png"], { type: "image/png" }), - } as Response); - }); - vi.stubGlobal("fetch", fetchMock); - - const source = `/api/chat/media/outgoing/agent%3Amain%3Amain/${crypto.randomUUID()}/full`; - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const client = { - request: vi.fn(async () => null), - } as unknown as Parameters[0]["client"]; - const sessions = {} as Parameters[0]["sessions"]; - const { pane, state } = createTestChatPane({ client, sessions }); - state.hello = { - auth: { deviceToken: "old-token" }, - } as typeof state.hello; - const messages = [ - { - role: "assistant", - content: [{ type: "image", url: source }], - timestamp: 1_000, - }, - ]; - const renderPane = () => { - render( - renderChatThread( - { - ...threadProps("pane-gateway-media-auth", state.sessionKey, messages), - assistantAttachmentAuthToken: resolveAssistantAttachmentAuthToken(state), - onRequestUpdate: renderPane, - }, - transcript, - ), - container, - ); - transcript.hostUpdated(); - }; - state.requestUpdate = renderPane; - - renderPane(); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const thumbnailSource = source.replace(/\/full$/u, "/thumbnail"); - const previousResource = observeChatMediaResource( - "managed-image", - `${thumbnailSource}::old-token::`, - ); - expect(fetchMock).toHaveBeenCalledTimes(1); - expect(previousResource.subscribers.size).toBe(1); - - pane.applyGatewaySnapshot({ - ...pane.context.gateway.snapshot, - client, - phase: "connected", - hello: { - ...pane.context.gateway.snapshot.hello, - auth: { deviceToken: "next-token" }, - } as typeof pane.context.gateway.snapshot.hello, - }); - expect(previousSignal?.aborted).toBe(true); - expect(isChatMediaResourceCurrent(previousResource)).toBe(false); - await flushDeferredRowPrune(); - - const nextResource = observeChatMediaResource( - "managed-image", - `${thumbnailSource}::next-token::`, - ); - expect(fetchMock).toHaveBeenCalledTimes(2); - expect(new Headers(fetchMock.mock.calls[1]?.[1]?.headers).get("Authorization")).toBe( - "Bearer next-token", - ); - expect(isChatMediaResourceCurrent(nextResource)).toBe(true); - expect(nextResource.subscribers.size).toBe(1); - expect(container.querySelector(".chat-message-image")?.src).toBe(blobUrl); - - releaseChatMediaResourceSubscriber(renderPane); - transcript.hostDisconnected(); - }); - - it("reconciles guarded local attachments when pane preview roots change", async () => { - let previousSignal: AbortSignal | undefined; - const fetchMock = vi.fn((_source: string, init?: RequestInit) => { - if (fetchMock.mock.calls.length === 1) { - return new Promise((_resolve, reject) => { - previousSignal = init?.signal ?? undefined; - previousSignal?.addEventListener( - "abort", - () => reject(new DOMException("preview roots changed", "AbortError")), - { once: true }, - ); - }); - } - return Promise.resolve({ - ok: true, - json: async () => ({ - available: true, - mediaTicket: "root-restored-ticket", - mediaTicketExpiresAt: new Date(Date.now() + 90_000).toISOString(), - }), - } as Response); - }); - vi.stubGlobal("fetch", fetchMock); - - const client = { - request: vi.fn(async () => null), - } as unknown as Parameters[0]["client"]; - const sessions = {} as Parameters[0]["sessions"]; - const { pane, state } = createTestChatPane({ client, sessions }); - const configPane = pane as typeof pane & { - applyApplicationConfig: (config: typeof pane.context.config.current) => void; - }; - state.hello = { - auth: { deviceToken: "old-token" }, - } as typeof state.hello; - state.localMediaPreviewRoots = ["/tmp/openclaw"]; - state.embedSandboxMode = "scripts"; - state.allowExternalEmbedUrls = false; - - const source = `/tmp/openclaw/${crypto.randomUUID()}.pdf`; - const messages = [ - { - role: "assistant", - content: `Local document\nMEDIA:${source}`, - timestamp: 1_000, - }, - ]; - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - const renderPane = () => { - render( - renderChatThread( - { - ...threadProps("pane-local-media-roots", state.sessionKey, messages), - assistantAttachmentAuthToken: resolveAssistantAttachmentAuthToken(state), - localMediaPreviewRoots: state.localMediaPreviewRoots, - onRequestUpdate: renderPane, - }, - transcript, - ), - container, - ); - transcript.hostUpdated(); - }; - state.requestUpdate = renderPane; - - renderPane(); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - const previousResource = observeChatMediaResource( - "assistant-attachment", - `::old-token::${source}`, - ); - expect(fetchMock).toHaveBeenCalledTimes(1); - expect(previousResource.subscribers.size).toBe(1); - - const config = { - ...pane.context.config.current, - localMediaPreviewRoots: ["/tmp/elsewhere"], - embedSandboxMode: "scripts" as const, - allowExternalEmbedUrls: false, - }; - configPane.applyApplicationConfig(config); - await flushDeferredRowPrune(); - - expect(previousSignal?.aborted).toBe(true); - expect(isChatMediaResourceCurrent(previousResource)).toBe(false); - expect(fetchMock).toHaveBeenCalledTimes(1); - expect( - container.querySelector(".chat-assistant-attachment-card__reason")?.textContent, - ).toContain("Outside allowed folders"); - - configPane.applyApplicationConfig({ - ...config, - localMediaPreviewRoots: ["/tmp/openclaw"], - }); - await flushDeferredRowPrune(); - - const restoredResource = observeChatMediaResource( - "assistant-attachment", - `::old-token::${source}`, - ); - expect(fetchMock).toHaveBeenCalledTimes(2); - expect(new Headers(fetchMock.mock.calls[1]?.[1]?.headers).get("Authorization")).toBe( - "Bearer old-token", - ); - expect(isChatMediaResourceCurrent(restoredResource)).toBe(true); - expect(restoredResource.subscribers.size).toBe(1); - expect( - container.querySelector(".chat-assistant-attachment-card__link")?.getAttribute("href"), - ).toContain("mediaTicket=root-restored-ticket"); - - releaseChatMediaResourceSubscriber(renderPane); - transcript.hostDisconnected(); - }); - - it("updates MCP App pinning when the same provider's capability changes", async () => { - const provider = { - sessionKey: "agent:main:main", - canPinWidgets: true, - canPinMcpApps: false, - pinMcpApp: vi.fn(async () => undefined), - snapshot$: { - value: { - sessionKey: "agent:main:main", - revision: 1, - tabs: [], - widgets: [], - }, - subscribe: () => () => undefined, - }, - }; - const props = { - ...threadProps("pane-mcp-capability"), - boardProvider: provider as unknown as BoardProvider, - messages: [ - { - role: "assistant", - timestamp: 1_000, - content: [ - { type: "text", text: "Here is the dashboard app." }, - { - type: "canvas", - preview: { - kind: "canvas", - surface: "assistant_message", - render: "url", - title: "Dashboard app", - viewId: "outer-view-must-not-be-pinned", - mcpApp: { - viewId: "view-dashboard-app", - serverName: "dashboard", - toolName: "show", - uiResourceUri: "ui://dashboard/app.html", - toolCallId: "call-dashboard-app", - originSessionKey: "agent:main:main", - }, - }, - }, - ], - }, - ], - }; - const transcript = createTestTranscript(); - const container = document.body.appendChild(document.createElement("div")); - - render(renderChatThread(props, transcript), container); - transcript.hostConnected(); - transcript.hostUpdated(); - await flushDeferredRowPrune(); - - expect(container.querySelector('[data-content-kind="mcp-app"]')).not.toBeNull(); - expect(container.querySelector("[data-pin-widget]")).toBeNull(); - - provider.canPinMcpApps = true; - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - - expect(container.querySelector("[data-pin-widget]")).not.toBeNull(); - expect(provider.snapshot$.value.revision).toBe(1); - - provider.canPinMcpApps = false; - render(renderChatThread(props, transcript), container); - transcript.hostUpdated(); - - expect(container.querySelector("[data-pin-widget]")).toBeNull(); - expect(provider.snapshot$.value.revision).toBe(1); - }); -}); diff --git a/ui/src/pages/chat/components/chat-thread.ts b/ui/src/pages/chat/components/chat-thread.ts index 6ffa96ffff3c..70fec717c2fe 100644 --- a/ui/src/pages/chat/components/chat-thread.ts +++ b/ui/src/pages/chat/components/chat-thread.ts @@ -1,1395 +1,22 @@ -// Chat-owned message thread presentation and thread-local interaction state. -import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice"; -import { VirtualizerController } from "@tanstack/lit-virtual"; -import { defaultRangeExtractor, observeElementRect } from "@tanstack/virtual-core"; -import { - html, - nothing, - type ReactiveController, - type ReactiveControllerHost, - type TemplateResult, -} from "lit"; -import { guard } from "lit/directives/guard.js"; -import { ref } from "lit/directives/ref.js"; -import { repeat } from "lit/directives/repeat.js"; -import { styleMap } from "lit/directives/style-map.js"; -import { classifySessionKind } from "../../../../../src/sessions/classify-session-kind.js"; -import type { SessionsListResult } from "../../../api/types.ts"; -import type { QuestionPrompt } from "../../../app/question-prompt.ts"; -import { resolveLocalUserName } from "../../../app/user-identity.ts"; -import { copyMarkdownLabel } from "../../../components/copy-button.ts"; -import { icons } from "../../../components/icons.ts"; -import type { ImageLightboxItem } from "../../../components/image-lightbox.ts"; +// Public chat transcript renderer and DOM shell. +import { html, nothing, type TemplateResult } from "lit"; import { handleMarkdownCodeBlockCopy } from "../../../components/markdown-code-blocks.ts"; import { markdownFileLinkFromEvent, markdownFileLinkFromKeyboardEvent, } from "../../../components/markdown-file-links.ts"; -import "../../../components/tooltip.ts"; -import { McpAppUnmountGate } from "../../../components/mcp-app-unmount.ts"; -import { i18n, t } from "../../../i18n/index.ts"; -import type { BoardProvider } from "../../../lib/board/provider.ts"; -import type { - ChatQueueItem, - ChatStreamSegment, - MessageGroup, -} from "../../../lib/chat/chat-types.ts"; +import { t } from "../../../i18n/index.ts"; import { - buildCompanionQuestionPrefill, - buildMoreDetailsCompanionQuestion, -} from "../../../lib/chat/companion-question.ts"; -import { extractTextCached } from "../../../lib/chat/message-extract.ts"; -import { normalizeMessage } from "../../../lib/chat/message-normalizer.ts"; -import type { EmbedSandboxMode } from "../../../lib/chat/tool-display.ts"; -import { copyToClipboard } from "../../../lib/clipboard.ts"; -import { fnv1aUtf16 } from "../../../lib/fnv1a.ts"; + handleTranscriptContextMenu, + handleTranscriptSelection, + type ChatThreadProps, +} from "./chat-thread-interactions.ts"; import { - areUiSessionKeysEquivalent, - isUiGlobalScopeConfigured, - parseAgentSessionKey, - resolveUiGlobalAliasAgentId, - type UiSessionDefaultsHost, -} from "../../../lib/sessions/session-key.ts"; -import { resolveTurnRecap, type TurnRecap } from "../chat-progress.ts"; -import type { ChatRunStartupStatus } from "../chat-run-startup.ts"; -import { - assistantGroupCanOwnActiveRunStatus, - assistantMessageExpansionSignature, - buildCachedChatItems, - coalesceActivityRuns, - coalesceStreamRuns, - collapseCompletedTurnWork, - getExpansionStateVersion, - getExpandedToolCards, - getExpandedAssistantMessages, - getExpandedUserMessages, - persistedMessageEntryId, - resetChatThreadState, - setExpansionState, - syncToolCardExpansionState, -} from "../chat-thread.ts"; -import { PinnedMessages } from "../pinned-messages.ts"; -import type { RealtimeTalkConversationEntry } from "../realtime-talk-conversation.ts"; -import { - CHAT_TRANSCRIPT_END_THRESHOLD_PX, - getChatSessionScrollPosition, - saveChatSessionScrollPosition, - type ChatSessionScrollPosition, -} from "../scroll.ts"; -import { getOrCreateSessionCacheValue } from "../session-cache.ts"; -import type { PlanStatus } from "../tool-stream.ts"; -import { getToolTitlesVersion } from "../tool-titles.ts"; -import { renderBackgroundTasksStatusRow } from "./chat-background-tasks-status.ts"; -import type { BackgroundTasksProps } from "./chat-background-tasks.types.ts"; -import { renderChatDivider, renderChatNotice } from "./chat-divider.ts"; -import { resolveMessageGroupSenderLabel } from "./chat-message-group.ts"; -import { resolveMessageReplyText } from "./chat-message-markdown.ts"; -import type { ArtifactDownloadResolver } from "./chat-message-media.ts"; -import { - dismissConfirmedActionPopovers, - getChatMediaRenderVersion, - openChatRewindConfirmation, - renderMessageGroup, - renderActivityGroup, - renderStreamGroup, - renderWorkGroupSummary, - type MessageReplyTarget, - type StreamGroupOptions, - type StreamGroupPart, -} from "./chat-message.ts"; -import { renderRealtimeTalkConversation } from "./chat-realtime-controls.ts"; -import { handleChatSelectionPointerUp, removeChatSelectionPopup } from "./chat-selection-popup.ts"; -import type { SidebarContent, SidebarFullMessageLoader } from "./chat-sidebar.ts"; -import { renderWelcomeState, resolveAssistantDisplayAvatar } from "./chat-welcome.ts"; -import { renderTurnRecapRow } from "./chat-working-indicator.ts"; - -const pinnedMessagesMap = new Map(); - -type ChatThreadState = { - searchOpen: boolean; - searchQuery: string; - searchFocusPending: boolean; - searchReturnFocusTarget: HTMLElement | null; - searchReturnFocusOwner: HTMLElement | null; - pinnedExpanded: boolean; - transcriptRenderDependencies: readonly unknown[]; - transcriptRenderContext: { - onSetReply?: ChatThreadProps["onSetReply"]; - onOpenReply?: (replyToId: string) => void; - }; -}; - -export type ChatReplyMessageAccess = { - revision: number; - navigationId: string | null; - read: (messageId: string) => unknown; - request: (messageId: string) => void; - open: (messageId: string) => void; -}; - -type ChatThreadProps = { - paneId: string; - sessionKey: string; - boardProvider?: BoardProvider; - announceTranscript?: boolean; - loading: boolean; - historyPagination?: { - loading: boolean; - }; - messages: unknown[]; - toolMessages: unknown[]; - streamSegments: ChatStreamSegment[]; - stream: string | null; - streamStartedAt: number | null; - runId?: string | null; - runOutputTokens?: number | null; - queue: ChatQueueItem[]; - showThinking: boolean; - showToolCalls: boolean; - persistCommentary?: boolean; - /** True while the session has an abortable live run (marks running tool rows). */ - runActive?: boolean; - /** True while the agent is visibly working (isChatRunWorking); shows the working spark. */ - runWorking?: boolean; - /** Coarse startup stage shown until assistant or tool activity becomes visible. */ - startupStatus?: ChatRunStartupStatus | null; - /** Re-labels the working spark while the active run is parked on an approval. */ - waitingApproval?: boolean; - planStatus?: PlanStatus | null; - questionPrompts?: readonly QuestionPrompt[]; - sessions: SessionsListResult | null; - /** Host context resolving global-alias session keys (scope=global fleets). */ - /** Includes assistantAgentId so bare-global welcome recents scope to the selected agent. */ - sessionHost?: UiSessionDefaultsHost | null; - gatewayUrl?: string; - assistantName: string; - assistantAvatar: string | null; - assistantAvatarUrl?: string | null; - userId?: string | null; - userName?: string | null; - userAvatar?: string | null; - basePath?: string; - fullMessageAgentId?: string; - loadFullAssistantMessage?: SidebarFullMessageLoader | null; - localMediaPreviewRoots?: string[]; - assistantAttachmentAuthToken?: string | null; - resolveArtifactDownload?: ArtifactDownloadResolver; - canvasPluginSurfaceUrl?: string | null; - embedSandboxMode?: EmbedSandboxMode; - allowExternalEmbedUrls?: boolean; - autoExpandToolCalls?: boolean; - realtimeTalkConversation?: RealtimeTalkConversationEntry[]; - onOpenSidebar?: (content: SidebarContent) => void; - onOpenWorkspaceFile?: (target: { path: string; line?: number | null }) => void; - onOpenSessionCheckpoints?: () => void | Promise; - onAssistantAttachmentLoaded?: () => void; - onRequestOpenImage?: () => number; - onOpenImage?: (item: ImageLightboxItem, requestVersion?: number) => void; - onRequestUpdate?: () => void; - onChatScroll?: (event: Event) => void; - onHistoryIntent?: (event: Event) => void; - onDraftChange: (next: string) => void; - onSend: () => void; - onSetReply?: (target: MessageReplyTarget) => void; - replyMessageAccess?: ChatReplyMessageAccess; - onRewindMessage?: (entryId: string) => Promise | boolean; - onForkMessage?: (entryId: string) => Promise | void; - onFocusComposer?: () => void; - onCompanionQuestion?: (question: string) => void; - onCompanionPrefill?: (question: string) => void; - onOpenSession?: (sessionKey: string) => void; - modelSetupRequired?: boolean; - onModelSetup?: () => void; - /** Tasks-rail snapshot backing the post-turn running-tasks status row. */ - backgroundTasks?: BackgroundTasksProps; -}; - -type ChatPinnedMessagesProps = Pick< - ChatThreadProps, - "paneId" | "sessionKey" | "messages" | "userName" | "userAvatar" ->; - -type ChatRenderItem = ReturnType[number]; - -type ChatTranscriptRow = - | { kind: "item"; key: string; item: ChatRenderItem } - | { kind: "content"; key: string; content: unknown }; - -type ChatTranscriptAnnouncement = { - key: string; - text: string; -}; - -type LoadedReplySource = { - rowKey: string; - preview: MessageReplyTarget & { sourceMessageId: string }; -}; - -function projectResolvedReplyPreview( - message: unknown, - replyToId: string, - props: Pick, -): LoadedReplySource["preview"] | undefined { - const normalized = normalizeMessage(message); - const text = resolveMessageReplyText(message); - if (!text) { - return undefined; - } - const group: MessageGroup = { - kind: "group", - key: replyToId, - role: normalized.role, - senderLabel: normalized.senderLabel, - ...(normalized.sender ? { sender: normalized.sender } : {}), - messages: [{ key: replyToId, message }], - timestamp: normalized.timestamp, - isStreaming: false, - }; - const sourceMessageId = persistedMessageEntryId(message) ?? replyToId; - return { - messageId: sourceMessageId, - sourceMessageId, - senderLabel: resolveMessageGroupSenderLabel(group, props), - text, - }; -} - -const CHAT_TRANSCRIPT_ESTIMATED_ROW_PX = 120; -const CHAT_TRANSCRIPT_OVERSCAN = 6; -const CHAT_TRANSCRIPT_ANNOUNCEMENT_MAX_CHARS = 500; -// Initial virtual rows can correct their estimates for several frames. Hold a -// restored offset for ~200ms so those corrections cannot reapply the end anchor. -const CHAT_TRANSCRIPT_SCROLL_RESTORE_STABLE_FRAMES = 12; -// A committed short transcript can legitimately remain at maxOffset=0. Give -// initial measurement one second before treating that zero range as final. -const CHAT_TRANSCRIPT_ZERO_MAX_SETTLE_FRAMES = 60; -function initialTranscriptRect(host: ReactiveControllerHost) { - const width = host instanceof HTMLElement ? host.clientWidth : 0; - const height = host instanceof HTMLElement ? host.clientHeight : 0; - return { - width: width || (typeof window === "undefined" ? 0 : window.innerWidth), - height: height || (typeof window === "undefined" ? 0 : window.innerHeight), - }; -} - -function transcriptScrollMargin(element: Element | null): number { - if (!(element instanceof HTMLElement) || typeof getComputedStyle !== "function") { - return 0; - } - const margin = Number.parseFloat(getComputedStyle(element).paddingTop); - return Number.isFinite(margin) ? margin : 0; -} - -function initialTranscriptScrollMargin(host: ReactiveControllerHost): number { - return host instanceof HTMLElement - ? transcriptScrollMargin(host.querySelector(".chat-thread")) - : 0; -} - -class ChatSessionVirtualizerHost implements ReactiveControllerHost { - private readonly controllers = new Set(); - private readonly virtualizerController: VirtualizerController; - private threadInnerElement: HTMLDivElement | null = null; - private connected = false; - private observedWidth: number | null = null; - private observedHeight: number | null = null; - private contentReady = false; - private pendingScrollOffset: { - offset: number; - stableFrames: number; - zeroMaxFrames: number; - onSettled?: (position: ChatSessionScrollPosition) => void; - } | null = null; - private pendingScrollFrame: number | null = null; - // Lit calls refs before newly rendered nodes are connected. Resolve the - // scroll parent lazily or a stable ref can permanently capture null. - private get scrollElement(): HTMLDivElement | null { - const parent = this.threadInnerElement?.parentElement; - return parent instanceof HTMLDivElement ? parent : null; - } - // Stable Lit refs: inline arrows change identity per render, making Lit - // re-invoke them for every visible row and re-measure each row every render. - // Lit tracks the last element per callback, so each row needs its own. - private readonly scrollElementRef = (element?: Element) => { - this.threadInnerElement = element instanceof HTMLDivElement ? element : null; - }; - private readonly measureRowRefs = new Map void>(); - private pruneDetachedRowsQueued = false; - private pendingRowMeasureFrame: number | null = null; - private measureConnectedRows(): void { - // Only width invalidation owns forced DOM reads. Ordinary row refs stay on - // TanStack's observer path so resizeItem cannot perturb scroll restoration. - const instance = this.virtualizerController.getVirtualizer(); - for (const row of this.threadInnerElement?.querySelectorAll(".chat-virtual-row") ?? - []) { - instance.resizeItem( - instance.indexFromElement(row), - row[instance.options.horizontal ? "offsetWidth" : "offsetHeight"], - ); - } - } - private queueConnectedRowMeasure(): void { - if (this.pendingRowMeasureFrame !== null) { - return; - } - this.pendingRowMeasureFrame = requestAnimationFrame(() => { - this.pendingRowMeasureFrame = null; - this.measureConnectedRows(); - }); - } - private measureRowRefFor(key: string): (element?: Element) => void { - let callback = this.measureRowRefs.get(key); - if (!callback) { - callback = (element?: Element) => { - if (element instanceof HTMLElement) { - this.virtualizerController.getVirtualizer().measureElement(element); - return; - } - // Re-stamps (e.g. the chat<->dashboard face switch) re-invoke each - // stable row ref as an (undefined, element) pair while the new subtree - // is still detached. measureElement(null) prunes every disconnected - // row, so calling it synchronously unobserves just-registered sibling - // rows and freezes their heights at the old pane width (overlapping - // bubbles). Defer until the commit lands so only removed rows prune. - if (this.pruneDetachedRowsQueued) { - return; - } - this.pruneDetachedRowsQueued = true; - queueMicrotask(() => { - this.pruneDetachedRowsQueued = false; - this.virtualizerController.getVirtualizer().measureElement(null); - }); - }; - this.measureRowRefs.set(key, callback); - } - return callback; - } - private rowKeys: readonly string[] = []; - private rowIndexesByKey = new Map(); - private messageRowKeysById = new Map(); - private focusedRowKey: string | null = null; - private announcementInitialized = false; - private announcementKey: string | null = null; - private currentAnnouncementText = ""; - private readonly mcpAppUnmountGate = new McpAppUnmountGate(this); - - constructor( - private readonly host: ReactiveControllerHost, - initialOffset: number | null = null, - onInitialOffsetSettled?: (position: ChatSessionScrollPosition) => void, - ) { - this.virtualizerController = new VirtualizerController(this, { - count: 0, - getScrollElement: () => this.scrollElement, - estimateSize: () => CHAT_TRANSCRIPT_ESTIMATED_ROW_PX, - getItemKey: () => "", - initialRect: initialTranscriptRect(host), - initialOffset: initialOffset ?? Number.MAX_SAFE_INTEGER, - scrollMargin: initialTranscriptScrollMargin(host), - anchorTo: "end", - followOnAppend: false, - observeElementRect: (instance, callback) => - observeElementRect(instance, (rect) => { - const previousHeight = this.observedHeight; - const widthChanged = this.observedWidth !== null && this.observedWidth !== rect.width; - const heightChanged = previousHeight !== null && previousHeight !== rect.height; - const scrollOffset = instance.scrollOffset; - const wasAtEndBeforeResize = - heightChanged && - this.pendingScrollOffset === null && - scrollOffset !== null && - instance.getTotalSize() - previousHeight - scrollOffset <= - CHAT_TRANSCRIPT_END_THRESHOLD_PX; - this.observedWidth = rect.width; - this.observedHeight = rect.height; - this.syncScrollMargin(instance.scrollElement); - callback(rect); - if (wasAtEndBeforeResize) { - instance.scrollToEnd({ behavior: "auto" }); - } - if (widthChanged) { - // Cached offscreen sizes belong to the old wrapping width. Reset - // them, seed current rows, then repeat after any same-commit - // re-stamp has attached and completed layout. - instance.measure(); - this.measureConnectedRows(); - this.queueConnectedRowMeasure(); - } - }), - rangeExtractor: (range) => { - const indexes = defaultRangeExtractor(range); - const focused = - this.focusedRowKey === null ? undefined : this.rowIndexesByKey.get(this.focusedRowKey); - if ( - focused === undefined || - focused < 0 || - focused >= range.count || - indexes.includes(focused) - ) { - return indexes; - } - return [...indexes, focused].toSorted((left, right) => left - right); - }, - scrollEndThreshold: CHAT_TRANSCRIPT_END_THRESHOLD_PX, - overscan: CHAT_TRANSCRIPT_OVERSCAN, - }); - if (initialOffset !== null) { - this.pendingScrollOffset = { - offset: initialOffset, - stableFrames: 0, - zeroMaxFrames: 0, - onSettled: onInitialOffsetSettled, - }; - } - } - - get updateComplete() { - return this.host.updateComplete; - } - - get liveAnnouncementText() { - return this.currentAnnouncementText; - } - - requestUpdate = () => { - this.host.requestUpdate(); - }; - - addController(controller: ReactiveController): void { - this.controllers.add(controller); - } - - removeController(controller: ReactiveController): void { - this.controllers.delete(controller); - } - - connect(): void { - if (this.connected) { - return; - } - this.connected = true; - for (const controller of this.controllers) { - controller.hostConnected?.(); - } - if (this.pendingScrollOffset) { - this.host.requestUpdate(); - } - } - - update(): void { - for (const controller of this.controllers) { - controller.hostUpdated?.(); - } - this.applyPendingScrollOffset(); - } - - disconnect(): void { - if (this.pendingRowMeasureFrame !== null) { - cancelAnimationFrame(this.pendingRowMeasureFrame); - this.pendingRowMeasureFrame = null; - } - if (this.pendingScrollFrame !== null) { - cancelAnimationFrame(this.pendingScrollFrame); - this.pendingScrollFrame = null; - } - if (!this.connected) { - this.threadInnerElement = null; - return; - } - this.connected = false; - for (const controller of this.controllers) { - controller.hostDisconnected?.(); - } - this.threadInnerElement = null; - } - - dispose(): void { - this.disconnect(); - this.measureRowRefs.clear(); - this.rowKeys = []; - this.rowIndexesByKey.clear(); - this.messageRowKeysById.clear(); - this.focusedRowKey = null; - this.pendingScrollOffset = null; - } - - render( - rows: readonly ChatTranscriptRow[], - renderRow: (row: ChatTranscriptRow) => unknown, - announcement: ChatTranscriptAnnouncement | null, - announce: boolean, - overlay: unknown = nothing, - ): TemplateResult { - this.syncRows(rows); - this.syncAnnouncement(announcement, announce); - const virtualizer = this.virtualizerController.getVirtualizer(); - const virtualRows = virtualizer.getVirtualItems(); - const nextRowKeys = new Set( - virtualRows.flatMap((virtualRow) => { - const row = rows[virtualRow.index]; - return row ? [row.key] : []; - }), - ); - const rendered = html` -
-
- ${overlay} - ${repeat( - virtualRows, - (virtualRow) => virtualRow.key, - (virtualRow) => { - const row = rows[virtualRow.index]; - if (!row) { - return nothing; - } - return html` -
- ${renderRow(row)} -
- `; - }, - )} -
-
- `; - return this.mcpAppUnmountGate.render(JSON.stringify([...nextRowKeys]), rendered, () => - this.threadInnerElement - ? [...this.threadInnerElement.querySelectorAll(".chat-virtual-row")].filter( - (row) => !nextRowKeys.has(row.dataset.virtualRowKey ?? ""), - ) - : [], - ) as TemplateResult; - } - - scrollToEnd(options: { behavior?: ScrollBehavior } = {}): void { - this.virtualizerController.getVirtualizer().scrollToEnd(options); - } - - scrollToOffset(offset: number): void { - if (this.scrollElement) { - this.scrollElement.scrollTop = offset; - } - this.virtualizerController.getVirtualizer().scrollToOffset(offset); - } - - syncMessageRows(messageRowKeysById: ReadonlyMap): void { - this.messageRowKeysById = new Map(messageRowKeysById); - } - - revealMessage(messageId: string): boolean { - const rowKey = this.messageRowKeysById.get(messageId); - if (!rowKey) { - return false; - } - const rowIndex = this.rowIndexesByKey.get(rowKey); - if (rowIndex === undefined) { - return false; - } - this.virtualizerController.getVirtualizer().scrollToIndex(rowIndex, { align: "center" }); - this.host.requestUpdate(); - void this.host.updateComplete.then(() => { - const bubble = [ - ...(this.threadInnerElement?.querySelectorAll(".chat-bubble") ?? []), - ].find((candidate) => candidate.dataset.entryId === messageId); - if (!bubble) { - return; - } - this.threadInnerElement - ?.querySelector(".chat-bubble--reply-target") - ?.classList.remove("chat-bubble--reply-target"); - bubble.scrollIntoView?.({ behavior: "smooth", block: "center" }); - bubble.classList.add("chat-bubble--reply-target"); - bubble.addEventListener( - "animationend", - () => bubble.classList.remove("chat-bubble--reply-target"), - { once: true }, - ); - }); - return true; - } - - getScrollOffset(): number | null { - return this.scrollElement?.scrollTop ?? null; - } - - getMaxScrollOffset(): number | null { - const scrollElement = this.scrollElement; - return scrollElement - ? Math.max(0, scrollElement.scrollHeight - scrollElement.clientHeight) - : null; - } - - setContentReady(ready: boolean): void { - this.contentReady = ready; - } - - restoreScrollOffset( - offset: number, - onSettled?: (position: ChatSessionScrollPosition) => void, - ): void { - this.pendingScrollOffset = { offset, stableFrames: 0, zeroMaxFrames: 0, onSettled }; - if (this.connected) { - this.host.requestUpdate(); - } - } - - getPendingScrollOffset(): number | null { - return this.pendingScrollOffset?.offset ?? null; - } - - handleFocusIn(event: FocusEvent): void { - this.focusedRowKey = this.rowKeyFromEvent(event); - } - - handleFocusOut(event: FocusEvent): void { - this.focusedRowKey = this.rowKeyFromEvent(event, event.relatedTarget); - } - - private rowKeyFromEvent(event: FocusEvent, target: EventTarget | null = event.target) { - if (!(target instanceof Element) || !this.scrollElement?.contains(target)) { - return null; - } - const row = target.closest(".chat-virtual-row[data-virtual-row-key]"); - if (!row || !this.scrollElement.contains(row)) { - return null; - } - return row.dataset.virtualRowKey || null; - } - - private syncAnnouncement( - announcement: ChatTranscriptAnnouncement | null, - announce: boolean, - ): void { - if (!this.announcementInitialized || !announce) { - this.announcementInitialized = true; - this.announcementKey = announcement?.key ?? null; - this.currentAnnouncementText = ""; - return; - } - if (!announcement || announcement.key === this.announcementKey) { - return; - } - this.announcementKey = announcement.key; - this.currentAnnouncementText = announcement.text; - } - - private syncRows(rows: readonly ChatTranscriptRow[]): void { - const nextKeys = rows.map((row) => row.key); - if ( - nextKeys.length === this.rowKeys.length && - nextKeys.every((key, index) => key === this.rowKeys[index]) - ) { - return; - } - this.rowKeys = Object.freeze(nextKeys); - this.rowIndexesByKey = new Map(this.rowKeys.map((key, index) => [key, index])); - for (const key of this.measureRowRefs.keys()) { - if (!this.rowIndexesByKey.has(key)) { - this.measureRowRefs.delete(key); - } - } - const keys = this.rowKeys; - const virtualizer = this.virtualizerController.getVirtualizer(); - virtualizer.setOptions({ - ...virtualizer.options, - count: keys.length, - getItemKey: (index) => keys[index] ?? `missing:${index}`, - }); - } - - private syncScrollMargin(scrollElement: HTMLDivElement | null): void { - const scrollMargin = transcriptScrollMargin(scrollElement); - const virtualizer = this.virtualizerController.getVirtualizer(); - if (scrollMargin === virtualizer.options.scrollMargin) { - return; - } - virtualizer.setOptions({ - ...virtualizer.options, - scrollMargin, - }); - } - - private applyPendingScrollOffset(): void { - const pending = this.pendingScrollOffset; - if (!pending || !this.connected) { - return; - } - const maxOffset = this.getMaxScrollOffset(); - if (maxOffset === null) { - if (this.contentReady && this.rowKeys.length === 0) { - this.settlePendingScroll(0); - } - return; - } - if (maxOffset === 0 && pending.offset > 0) { - if (this.contentReady && this.rowKeys.length === 0) { - this.settlePendingScroll(0); - } else if (this.contentReady) { - if (pending.zeroMaxFrames >= CHAT_TRANSCRIPT_ZERO_MAX_SETTLE_FRAMES) { - this.settlePendingScroll(0); - return; - } - pending.zeroMaxFrames += 1; - this.schedulePendingScrollRetry(); - } - return; - } - pending.zeroMaxFrames = 0; - const targetOffset = Math.min(pending.offset, maxOffset); - this.scrollToOffset(targetOffset); - const currentOffset = this.getScrollOffset(); - if (currentOffset != null && Math.abs(currentOffset - targetOffset) <= 1) { - if (pending.stableFrames >= CHAT_TRANSCRIPT_SCROLL_RESTORE_STABLE_FRAMES) { - this.settlePendingScroll(currentOffset); - } else { - pending.stableFrames += 1; - this.schedulePendingScrollRetry(); - } - } else { - pending.stableFrames = 0; - this.schedulePendingScrollRetry(); - } - } - - private schedulePendingScrollRetry(): void { - if (!this.connected || this.pendingScrollFrame !== null) { - return; - } - this.pendingScrollFrame = requestAnimationFrame(() => { - this.pendingScrollFrame = null; - if (this.connected && this.pendingScrollOffset) { - this.host.requestUpdate(); - } - }); - } - - private settlePendingScroll(scrollTop: number): void { - const pending = this.pendingScrollOffset; - this.pendingScrollOffset = null; - if (!pending) { - return; - } - const maxScrollTop = this.getMaxScrollOffset(); - pending.onSettled?.({ - scrollTop, - anchorToEnd: - maxScrollTop === null - ? this.contentReady && this.rowKeys.length === 0 - : maxScrollTop - scrollTop <= CHAT_TRANSCRIPT_END_THRESHOLD_PX, - }); - } -} - -export class ChatTranscriptController implements ReactiveController { - private activeSessionKey: string | null = null; - private sessionVirtualizer: ChatSessionVirtualizerHost | null = null; - private connected = false; - - constructor(private readonly host: ReactiveControllerHost) { - host.addController(this); - } - - get renderedSessionKey(): string | null { - return this.activeSessionKey; - } - - render(props: ChatThreadProps): TemplateResult { - if ( - !this.sessionVirtualizer || - this.activeSessionKey === null || - !areUiSessionKeysEquivalent(this.activeSessionKey, props.sessionKey) - ) { - this.sessionVirtualizer?.dispose(); - const savedPosition = getChatSessionScrollPosition(props.paneId, props.sessionKey); - const initialOffset = savedPosition?.anchorToEnd ? null : (savedPosition?.scrollTop ?? null); - this.activeSessionKey = props.sessionKey; - this.sessionVirtualizer = new ChatSessionVirtualizerHost( - this.host, - initialOffset, - initialOffset === null - ? undefined - : (position) => { - saveChatSessionScrollPosition(props.paneId, props.sessionKey, position); - }, - ); - if (this.connected) { - this.sessionVirtualizer.connect(); - } - } - return renderChatThreadContents(props, this.sessionVirtualizer); - } - - scrollToEnd(options: { behavior?: ScrollBehavior } = {}): void { - this.sessionVirtualizer?.scrollToEnd(options); - } - - scrollToOffset(offset: number, onSettled?: (position: ChatSessionScrollPosition) => void): void { - this.sessionVirtualizer?.restoreScrollOffset(offset, onSettled); - } - - revealMessage(messageId: string): boolean { - return this.sessionVirtualizer?.revealMessage(messageId) ?? false; - } - - pendingScrollOffsetFor(sessionKey: string): number | null { - return this.activeSessionKey !== null && - areUiSessionKeysEquivalent(this.activeSessionKey, sessionKey) - ? (this.sessionVirtualizer?.getPendingScrollOffset() ?? null) - : null; - } - - handleFocusIn(event: FocusEvent): void { - this.sessionVirtualizer?.handleFocusIn(event); - } - - handleFocusOut(event: FocusEvent): void { - this.sessionVirtualizer?.handleFocusOut(event); - } - - hostConnected(): void { - this.connected = true; - this.sessionVirtualizer?.connect(); - } - - hostUpdated(): void { - this.sessionVirtualizer?.update(); - } - - hostDisconnected(): void { - this.connected = false; - this.sessionVirtualizer?.disconnect(); - } -} - -function createChatThreadState(): ChatThreadState { - return { - searchOpen: false, - searchQuery: "", - searchFocusPending: false, - searchReturnFocusTarget: null, - searchReturnFocusOwner: null, - pinnedExpanded: false, - transcriptRenderDependencies: [], - transcriptRenderContext: {}, - }; -} - -const threadStates = new Map(); - -function getChatThreadState(paneId: string): ChatThreadState { - const existing = threadStates.get(paneId); - if (existing) { - return existing; - } - const state = createChatThreadState(); - threadStates.set(paneId, state); - return state; -} - -function getPinnedMessages(sessionKey: string): PinnedMessages { - return getOrCreateSessionCacheValue( - pinnedMessagesMap, - sessionKey, - () => new PinnedMessages(sessionKey), - ); -} - -function getPinnedMessageSummary(message: unknown): string { - return extractTextCached(message) ?? ""; -} - -function dismissChatThreadPortals(paneId?: string, owner?: ParentNode): void { - removeReplyContextMenu(paneId); - if (owner) { - dismissConfirmedActionPopovers(owner); - } - // The selection popup is body-portaled; pane teardown/route changes must - // drop it so it cannot outlive the render that owns its callbacks. - removeChatSelectionPopup(); -} - -export function resetChatThreadSessionPresentationState(paneId: string, owner?: ParentNode): void { - dismissChatThreadPortals(paneId, owner); - const state = threadStates.get(paneId); - if (state) { - // Search input belongs to the outgoing transcript. Other fields are pane - // preferences or dependency memos and invalidate themselves on new props. - state.searchOpen = false; - state.searchQuery = ""; - state.searchFocusPending = false; - state.searchReturnFocusTarget = null; - state.searchReturnFocusOwner = null; - } -} - -export function resetChatThreadPresentationState(paneId?: string, owner?: ParentNode) { - dismissChatThreadPortals(paneId, owner); - if (paneId) { - threadStates.delete(paneId); - resetChatThreadState(paneId); - } else { - threadStates.clear(); - resetChatThreadState(); - } -} - -export function renderChatSearchBar( - paneId: string, - requestUpdate: () => void, -): TemplateResult | typeof nothing { - const state = getChatThreadState(paneId); - if (!state.searchOpen) { - return nothing; - } - return html` -
- ${icons.search} - { - if (element instanceof HTMLInputElement) { - state.searchFocusPending = false; - queueMicrotask(() => { - if (element.isConnected) { - element.focus({ preventScroll: true }); - } - }); - } - }) - : nothing} - @input=${(event: Event) => { - state.searchQuery = (event.target as HTMLInputElement).value; - requestUpdate(); - }} - /> - - - -
- `; -} - -function closeChatThreadSearch(state: ChatThreadState, requestUpdate: () => void): void { - const returnFocusTarget = state.searchReturnFocusTarget; - const returnFocusOwner = state.searchReturnFocusOwner; - state.searchOpen = false; - state.searchQuery = ""; - state.searchFocusPending = false; - state.searchReturnFocusTarget = null; - state.searchReturnFocusOwner = null; - requestUpdate(); - queueMicrotask(() => { - const target = returnFocusTarget?.isConnected - ? returnFocusTarget - : returnFocusOwner?.querySelector( - ".agent-chat__composer-combobox > textarea", - ); - target?.focus({ preventScroll: true }); - }); -} - -/** Toggles transcript search and retains the shortcut origin for focus restoration. */ -export function toggleChatThreadSearch( - paneId: string, - requestUpdate: () => void, - triggerEvent?: Event, -): void { - const state = getChatThreadState(paneId); - if (state.searchOpen) { - closeChatThreadSearch(state, requestUpdate); - return; - } - - state.searchOpen = true; - state.searchFocusPending = true; - const returnFocusTarget = triggerEvent?.target; - const returnFocusOwner = triggerEvent?.currentTarget; - state.searchReturnFocusTarget = - returnFocusTarget instanceof HTMLElement && returnFocusTarget.isConnected - ? returnFocusTarget - : null; - state.searchReturnFocusOwner = - returnFocusOwner instanceof HTMLElement && returnFocusOwner.isConnected - ? returnFocusOwner - : null; - requestUpdate(); -} - -export function renderChatPinnedMessages( - props: ChatPinnedMessagesProps, - requestUpdate: () => void, -): TemplateResult | typeof nothing { - const state = getChatThreadState(props.paneId); - const pinned = getPinnedMessages(props.sessionKey); - const userRoleLabel = resolveLocalUserName({ - name: props.userName ?? null, - avatar: props.userAvatar ?? null, - }); - const messages = Array.isArray(props.messages) ? props.messages : []; - const entries: Array<{ index: number; text: string; role: string }> = []; - for (const idx of pinned.indices) { - const msg = messages[idx] as Record | undefined; - if (!msg) { - continue; - } - const text = getPinnedMessageSummary(msg); - const role = typeof msg.role === "string" ? msg.role : "unknown"; - entries.push({ index: idx, text, role }); - } - if (entries.length === 0) { - return nothing; - } - return html` -
- - ${state.pinnedExpanded - ? html` -
- ${entries.map( - ({ index, text, role }) => html` -
- ${role === "user" ? userRoleLabel : t("common.assistant")} - ${truncateUtf16Safe(text, 100)}${text.length > 100 ? "..." : ""} - - - -
- `, - )} -
- ` - : nothing} -
- `; -} - -let activeReplyContextMenu: HTMLElement | null = null; -let activeReplyContextMenuPaneId: string | null = null; -let contextMenuDocumentClickHandler: ((event: MouseEvent) => void) | null = null; -let contextMenuDocumentContextMenuHandler: ((event: MouseEvent) => void) | null = null; -let contextMenuKeydownHandler: ((event: KeyboardEvent) => void) | null = null; - -function removeReplyContextMenu(paneId?: string) { - if (paneId && paneId !== activeReplyContextMenuPaneId) { - return; - } - if (activeReplyContextMenu) { - dismissConfirmedActionPopovers(activeReplyContextMenu); - activeReplyContextMenu.remove(); - } - activeReplyContextMenu = null; - activeReplyContextMenuPaneId = null; - const fallbackMenu = document.querySelector(".chat-reply-context-menu"); - if (fallbackMenu) { - dismissConfirmedActionPopovers(fallbackMenu); - fallbackMenu.remove(); - } - if (contextMenuDocumentClickHandler) { - document.removeEventListener("click", contextMenuDocumentClickHandler); - contextMenuDocumentClickHandler = null; - } - if (contextMenuDocumentContextMenuHandler) { - document.removeEventListener("contextmenu", contextMenuDocumentContextMenuHandler, true); - contextMenuDocumentContextMenuHandler = null; - } - if (contextMenuKeydownHandler) { - document.removeEventListener("keydown", contextMenuKeydownHandler); - contextMenuKeydownHandler = null; - } -} - -function stableReplyMessageId(senderLabel: string | undefined, text: string): string { - const source = `${senderLabel ?? ""}\n${text}`; - return `reply:${fnv1aUtf16(source).toString(16)}`; -} - -function createReplyContextMenuButton(onClick: () => void): HTMLButtonElement { - const button = document.createElement("button"); - button.type = "button"; - button.setAttribute("role", "menuitem"); - button.setAttribute("aria-label", t("chat.messages.replyToMessage")); - button.textContent = t("chat.messages.reply"); - button.addEventListener("click", onClick); - return button; -} - -function createMessageActionContextButton(params: { - label: string; - disabled: boolean; - tooltip: string; - onClick: () => void; -}): { element: HTMLElement; button: HTMLButtonElement } { - const button = document.createElement("button"); - button.type = "button"; - button.disabled = params.disabled; - button.setAttribute("role", "menuitem"); - button.setAttribute("aria-label", params.label); - button.textContent = params.label; - button.addEventListener("click", params.onClick); - const tooltip = document.createElement("openclaw-tooltip"); - tooltip.content = params.tooltip; - tooltip.append(button); - return { element: tooltip, button }; -} - -function handleChatThreadSelectionPointerUp(event: PointerEvent, props: ChatThreadProps) { - if ( - typeof props.onCompanionQuestion !== "function" || - typeof props.onCompanionPrefill !== "function" - ) { - return; - } - handleChatSelectionPointerUp(event, { - onMoreDetails: (selection) => { - const question = buildMoreDetailsCompanionQuestion(selection); - if (question) { - props.onCompanionQuestion?.(question); - } - }, - onAskSideChat: (selection) => { - const question = buildCompanionQuestionPrefill(selection); - if (question) { - props.onCompanionPrefill?.(question); - } - }, - }); -} - -function selectionIntersectsElement(selection: Selection | null, element: Element): boolean { - if (!selection || selection.isCollapsed) { - return false; - } - for (let index = 0; index < selection.rangeCount; index += 1) { - if (selection.getRangeAt(index).intersectsNode(element)) { - return true; - } - } - return false; -} - -function handleChatContextMenu(event: MouseEvent, props: ChatThreadProps) { - if (event.composedPath().some((target) => target instanceof HTMLAnchorElement)) { - return; - } - const bubble = (event.target as HTMLElement).closest(".chat-bubble"); - if (!bubble) { - return; - } - const group = bubble.closest(".chat-group"); - if (!group) { - return; - } - if ( - group.querySelector(".chat-reading-indicator") || - group.querySelector(".chat-bubble.streaming") - ) { - return; - } - const senderEl = group.querySelector(".chat-sender-name"); - const senderLabel = senderEl?.textContent?.trim() ?? undefined; - const text = truncateUtf16Safe((bubble as HTMLElement).dataset.messageText?.trim() ?? "", 500); - const entryId = (bubble as HTMLElement).dataset.entryId?.trim() ?? ""; - const messageId = (bubble as HTMLElement).dataset.messageId?.trim() ?? ""; - const isUserMessage = group.classList.contains("user") && Boolean(entryId); - // Grouped rows can contain several bubbles. Match the clicked bubble to its - // own action owner so copy never targets a sibling message. - const actionOwner = [...group.querySelectorAll("[data-message-actions-for]")].find( - (element) => element.dataset.messageActionsFor === messageId, - ); - const copyButton = actionOwner?.querySelector(".chat-copy-btn"); - const canReply = Boolean(text && props.onSetReply); - const canRewind = isUserMessage && typeof props.onRewindMessage === "function"; - const canCopy = Boolean(copyButton); - const canFork = isUserMessage && typeof props.onForkMessage === "function"; - if (!canReply && !canRewind && !canCopy && !canFork) { - return; - } - - const selection = window.getSelection(); - const selectedText = selectionIntersectsElement(selection, bubble) ? selection?.toString() : ""; - - event.preventDefault(); - event.stopPropagation(); - removeReplyContextMenu(); - const menu = document.createElement("div"); - menu.className = "chat-reply-context-menu"; - menu.setAttribute("role", "menu"); - menu.setAttribute("aria-label", t("chat.messages.actions")); - menu.style.left = `${event.clientX}px`; - menu.style.top = `${event.clientY}px`; - const focusCandidates: HTMLButtonElement[] = []; - if (selectedText) { - const action = createMessageActionContextButton({ - label: t("chat.messages.copySelection"), - disabled: false, - tooltip: t("chat.messages.copySelection"), - onClick: () => { - void copyToClipboard(selectedText); - removeReplyContextMenu(); - }, - }); - menu.append(action.element); - focusCandidates.push(action.button); - } - if (canReply) { - const replyMessageId = messageId || stableReplyMessageId(senderLabel, text); - const replyButton = createReplyContextMenuButton(() => { - props.onSetReply?.({ - messageId: replyMessageId, - text, - senderLabel, - ...(entryId ? { sourceMessageId: entryId } : {}), - }); - removeReplyContextMenu(); - props.onFocusComposer?.(); - }); - menu.append(replyButton); - focusCandidates.push(replyButton); - } - const working = Boolean(props.runActive || props.runWorking); - if (canRewind) { - const action = createMessageActionContextButton({ - label: t("chat.messages.rewindToHere"), - disabled: working, - tooltip: working ? t("chat.messages.rewindUnavailable") : t("chat.messages.rewindToHere"), - onClick: () => { - openChatRewindConfirmation(action.button, () => { - removeReplyContextMenu(); - void Promise.resolve(props.onRewindMessage?.(entryId)).then((rewound) => { - if (rewound) { - props.onFocusComposer?.(); - } - }); - }); - }, - }); - action.element.classList.add("chat-confirm-wrap", "chat-rewind-wrap"); - menu.append(action.element); - focusCandidates.push(action.button); - } - if (canCopy) { - const action = createMessageActionContextButton({ - label: copyMarkdownLabel(), - disabled: false, - tooltip: copyMarkdownLabel(), - onClick: () => { - removeReplyContextMenu(); - copyButton?.click(); - }, - }); - menu.append(action.element); - focusCandidates.push(action.button); - } - if (canFork) { - const action = createMessageActionContextButton({ - label: t("chat.messages.forkFromHere"), - disabled: working, - tooltip: working ? t("chat.messages.forkUnavailable") : t("chat.messages.forkFromHere"), - onClick: () => { - removeReplyContextMenu(); - void props.onForkMessage?.(entryId); - }, - }); - menu.append(action.element); - focusCandidates.push(action.button); - } - document.body.appendChild(menu); - activeReplyContextMenu = menu; - activeReplyContextMenuPaneId = props.paneId; - - const menuRect = menu.getBoundingClientRect(); - let left = event.clientX; - let top = event.clientY; - if (left + menuRect.width > window.innerWidth) { - left = window.innerWidth - menuRect.width - 8; - } - if (top + menuRect.height > window.innerHeight) { - top = window.innerHeight - menuRect.height - 8; - } - menu.style.left = `${Math.max(0, left)}px`; - menu.style.top = `${Math.max(0, top)}px`; - focusCandidates.find((button) => !button.disabled)?.focus(); - requestAnimationFrame(() => { - if (!menu.isConnected || activeReplyContextMenu !== menu) { - return; - } - contextMenuDocumentClickHandler = (nextEvent: MouseEvent) => { - if (!menu.contains(nextEvent.target as Node | null)) { - removeReplyContextMenu(); - } - }; - contextMenuDocumentContextMenuHandler = (nextEvent: MouseEvent) => { - if (!menu.contains(nextEvent.target as Node | null)) { - removeReplyContextMenu(); - } - }; - const handleKeydown = (nextEvent: KeyboardEvent) => { - if (nextEvent.key === "Escape") { - nextEvent.preventDefault(); - nextEvent.stopPropagation(); - removeReplyContextMenu(); - props.onFocusComposer?.(); - } - }; - contextMenuKeydownHandler = handleKeydown; - document.addEventListener("click", contextMenuDocumentClickHandler); - // Capture closes this owner even when the next menu stops event propagation. - document.addEventListener("contextmenu", contextMenuDocumentContextMenuHandler, true); - document.addEventListener("keydown", handleKeydown); - }); -} + type ChatTranscriptSession, + ChatTranscriptController, +} from "./chat-transcript-controller.ts"; +import { projectChatTranscript } from "./chat-transcript-projection.ts"; +import { renderWelcomeState } from "./chat-welcome.ts"; function renderLoadingSkeleton() { return html` @@ -1446,600 +73,42 @@ function renderHistorySentinel(loading: boolean) { `; } -function latestTranscriptAnnouncement( - items: readonly ChatRenderItem[], -): ChatTranscriptAnnouncement | null { - for (let itemIndex = items.length - 1; itemIndex >= 0; itemIndex -= 1) { - const item = items[itemIndex]; - if (!item || item.kind !== "group" || item.role.toLowerCase() !== "assistant") { - continue; - } - for (let messageIndex = item.messages.length - 1; messageIndex >= 0; messageIndex -= 1) { - const message = item.messages[messageIndex]?.message; - const text = extractTextCached(message)?.trim(); - if (text) { - return { - key: item.key, - text: truncateUtf16Safe(text, CHAT_TRANSCRIPT_ANNOUNCEMENT_MAX_CHARS), - }; - } - } - } - return null; -} - -function chatRenderItemGuardDependencies(item: ChatRenderItem): readonly unknown[] { - if (item.kind === "stream-run") { - return [item.key, ...item.parts]; - } - if (item.kind === "work-group") { - return [item.key, item.durationMs, item.hasError, ...item.groups]; - } - if (item.kind === "activity-run") { - return [item.key, ...item.groups]; - } - return [item]; -} - -function trackTranscriptRenderDependencies( - state: ChatThreadState, - dependencies: unknown[], -): unknown[] { - const previous = state.transcriptRenderDependencies; - const nextLength = dependencies.length - 1; - let changed = previous.length !== nextLength; - for (let index = 0; !changed && index < nextLength; index += 1) { - changed = !Object.is(previous[index], dependencies[index + 1]); - } - if (changed) { - // The first dependency is chatItems. Keep the shared context stable when - // only the live row changes, but invalidate every row for presentation changes. - state.transcriptRenderDependencies = dependencies.slice(1); - state.transcriptRenderContext = {}; - } - return dependencies; -} - -function guardChatRenderItems( - state: ChatThreadState, - // Live run status is not derivable from a row's own item identity: ownership - // is decided by sibling rows, and the usage counter ticks on run patches that - // touch nothing else. Rows showing status must re-render on both, or the - // memoized copy stacks a second claw row or freezes the token count. - liveStatus: (item: ChatRenderItem) => string, - render: (item: ChatRenderItem) => unknown, -) { - return (item: ChatRenderItem) => - guard( - [...chatRenderItemGuardDependencies(item), state.transcriptRenderContext, liveStatus(item)], - () => render(item), - ); -} - export function renderChatThread( props: ChatThreadProps, transcript: ChatTranscriptController, ): TemplateResult { - return transcript.render(props); + return transcript.renderSession(props.paneId, props.sessionKey, (session) => + renderTranscriptShell(props, session), + ); } -function renderChatThreadContents( +function renderTranscriptShell( props: ChatThreadProps, - transcript: ChatSessionVirtualizerHost, + transcript: ChatTranscriptSession, ): TemplateResult { - const state = getChatThreadState(props.paneId); - const requestUpdate = props.onRequestUpdate ?? (() => {}); - const displayStream = props.stream ?? null; - const sessionHost = props.sessionHost ?? null; - // Equivalence, not exact match: the default session travels under alias - // keys ("main" vs "agent:main:main") depending on the caller. - const activeSession = props.sessions?.sessions?.find((row) => - areUiSessionKeysEquivalent(row.key, props.sessionKey), - ); - // Global-alias detection needs no session row: under configured global - // scope, agent::global and configured-main aliases route to the global - // stream even when the capped sessions list omits the canonical row (or it - // does not exist yet). The scope gate keeps per-sender main threads direct. - const isGlobalAliasKey = - parseAgentSessionKey(props.sessionKey)?.rest === "global" || - (sessionHost !== null && - isUiGlobalScopeConfigured(sessionHost) && - resolveUiGlobalAliasAgentId(sessionHost, props.sessionKey) !== null); - const reasoningLevel = activeSession?.reasoningLevel ?? "off"; - const showReasoning = props.showThinking && reasoningLevel !== "off"; - const assistantIdentity = { - name: props.assistantName, - avatar: resolveAssistantDisplayAvatar(props), - }; - const locale = i18n.getLocale(); - const searchFiltering = state.searchOpen && Boolean(state.searchQuery.trim()); - const chatItems = buildCachedChatItems({ - paneId: props.paneId, - sessionKey: props.sessionKey, - runId: props.runId === undefined ? (activeSession?.activeRunIds?.[0] ?? null) : props.runId, - locale, - messages: props.messages, - toolMessages: props.toolMessages, - streamSegments: props.streamSegments, - stream: displayStream, - streamStartedAt: props.streamStartedAt, - queue: props.queue, - showToolCalls: props.showToolCalls, - persistCommentary: props.persistCommentary, - runWorking: Boolean(props.runWorking), - runActive: Boolean(props.runActive), - planStatus: props.planStatus, - questionPrompts: props.questionPrompts, - loading: props.loading, - searchOpen: state.searchOpen, - searchQuery: state.searchQuery, - }); - syncToolCardExpansionState( - props.sessionKey, - chatItems, - Boolean(props.autoExpandToolCalls), - searchFiltering || !props.showToolCalls, - ); - const expandedToolCards = getExpandedToolCards(props.sessionKey); - const expandedUserMessages = getExpandedUserMessages(props.sessionKey); - const expandedAssistantMessages = getExpandedAssistantMessages(props.sessionKey); - const questionPrompts = new Map( - (props.questionPrompts ?? []).map((prompt) => [prompt.id, prompt]), - ); - const toggleToolCardExpanded = (toolCardId: string) => { - setExpansionState(expandedToolCards, toolCardId, !expandedToolCards.get(toolCardId)); - requestUpdate(); - }; - const toggleAssistantMessageExpanded = (messageId: string) => { - const current = expandedAssistantMessages.get(messageId); - if (current?.status === "loaded") { - expandedAssistantMessages.set(messageId, { - ...current, - expanded: !current.expanded, - revision: current.revision + 1, - }); - requestUpdate(); - return; - } - const loader = props.loadFullAssistantMessage; - if (!loader || current?.status === "loading") { - return; - } - const revision = (current?.revision ?? 0) + 1; - expandedAssistantMessages.set(messageId, { status: "loading", revision }); - requestUpdate(); - void loader({ - sessionKey: props.sessionKey, - ...(props.fullMessageAgentId ? { agentId: props.fullMessageAgentId } : {}), - messageId, - kind: "assistant_message", - }).then( - (result) => { - const pending = expandedAssistantMessages.get(messageId); - if (pending?.status !== "loading" || pending.revision !== revision) { - return; - } - const markdown = - result?.ok && result.message && typeof result.message === "object" - ? extractTextCached(result.message) - : null; - expandedAssistantMessages.set( - messageId, - markdown === null - ? { status: "error", revision: revision + 1 } - : { status: "loaded", expanded: true, markdown, revision: revision + 1 }, - ); - requestUpdate(); - }, - () => { - const pending = expandedAssistantMessages.get(messageId); - if (pending?.status !== "loading" || pending.revision !== revision) { - return; - } - expandedAssistantMessages.set(messageId, { status: "error", revision: revision + 1 }); - requestUpdate(); - }, - ); - }; - const hasRealtimeTalkConversation = (props.realtimeTalkConversation?.length ?? 0) > 0; - const isEmpty = chatItems.length === 0 && !props.loading && !hasRealtimeTalkConversation; - transcript.setContentReady(!props.loading); - // 1:1 sessions drop the avatar gutter entirely; group threads keep avatars - // as the always-visible identity marker. The canonical session kind decides; - // the sessions list is capped, so absent/unknown rows classify by key: - // global aliases first, then the same core key-shape helper the gateway - // uses. Message senderLabels are not a signal here: gateway sanitization - // labels 1:1 channel DM rows too. - const rowKind = activeSession?.kind; - const sessionKind = - rowKind && rowKind !== "unknown" - ? rowKind - : isGlobalAliasKey - ? "global" - : classifySessionKind(props.sessionKey); - // Only agent-solo kinds qualify: "global" aggregates every inbound context - // under session.scope="global" (including group/channel senders), so it - // keeps avatars like "group" and "unknown" do. An identity-resolving gateway - // (multi-user trusted proxy) also keeps them: several people share these - // sessions, so the author marker is signal, not decoration. - const isDirectThread = - (sessionKind === "direct" || sessionKind === "cron" || sessionKind === "spawn-child") && - !props.userId; - const showLoadingSkeleton = props.loading && chatItems.length === 0; - const threadContextWindow = - activeSession?.contextTokens ?? props.sessions?.defaults?.contextTokens ?? null; - const activeContinuationByGroupKey = new Map< - string, - { parts: StreamGroupPart[]; options: StreamGroupOptions } - >(); - const turnRecapByGroupKey = new Map(); - const loadedReplySources = new Map(); - const resolvedReplyPreviews = new Map(); - const resolveReplyPreview = (replyToId: string) => { - const loaded = loadedReplySources.get(replyToId)?.preview; - if (loaded) { - return loaded; - } - if (resolvedReplyPreviews.has(replyToId)) { - return resolvedReplyPreviews.get(replyToId); - } - const message = props.replyMessageAccess?.read(replyToId); - const preview = message ? projectResolvedReplyPreview(message, replyToId, props) : undefined; - resolvedReplyPreviews.set(replyToId, preview); - return preview; - }; - const sharedMessageRenderOptions = { - onOpenSidebar: props.onOpenSidebar, - sessionKey: props.sessionKey, - boardProvider: props.boardProvider, - agentId: props.fullMessageAgentId, - runActive: props.runActive, - onOpenWorkspaceFile: props.onOpenWorkspaceFile, - onRequestUpdate: requestUpdate, - basePath: props.basePath, - localMediaPreviewRoots: props.localMediaPreviewRoots ?? [], - assistantAttachmentAuthToken: props.assistantAttachmentAuthToken ?? null, - resolveArtifactDownload: props.resolveArtifactDownload, - onAssistantAttachmentLoaded: props.onAssistantAttachmentLoaded, - onRequestOpenImage: props.onRequestOpenImage, - onOpenImage: props.onOpenImage, - canvasPluginSurfaceUrl: props.canvasPluginSurfaceUrl, - embedSandboxMode: props.embedSandboxMode ?? "scripts", - allowExternalEmbedUrls: props.allowExternalEmbedUrls ?? false, - showAssistantAvatar: false, - } satisfies StreamGroupOptions; - const streamGroupOptions = { - ...sharedMessageRenderOptions, - assistant: assistantIdentity, - } satisfies StreamGroupOptions; - const renderGroupOptions = (item: MessageGroup) => { - const lastMessage = item.messages.at(-1)?.message; - const rewindEntryId = - item.role.toLowerCase() === "user" && lastMessage - ? persistedMessageEntryId(lastMessage) - : null; - return { - ...sharedMessageRenderOptions, - showReasoning, - showToolCalls: props.showToolCalls, - autoExpandToolCalls: Boolean(props.autoExpandToolCalls), - isToolMessageExpanded: (messageId: string) => expandedToolCards.get(messageId), - onToggleToolMessageExpanded: (messageId: string, expanded?: boolean) => { - setExpansionState( - expandedToolCards, - messageId, - !(expanded ?? expandedToolCards.get(messageId) ?? false), - ); - requestUpdate(); - }, - isUserMessageExpanded: (messageId: string) => expandedUserMessages.get(messageId) ?? false, - onToggleUserMessageExpanded: (messageId: string) => { - setExpansionState(expandedUserMessages, messageId, !expandedUserMessages.get(messageId)); - requestUpdate(); - }, - loadFullAssistantMessage: props.loadFullAssistantMessage ?? undefined, - getAssistantMessageExpansion: (messageId: string) => expandedAssistantMessages.get(messageId), - onToggleAssistantMessageExpanded: toggleAssistantMessageExpanded, - isToolExpanded: (toolCardId: string) => expandedToolCards.get(toolCardId) ?? false, - onToggleToolExpanded: toggleToolCardExpanded, - assistantName: props.assistantName, - assistantAvatar: assistantIdentity.avatar, - userId: props.userId ?? null, - userName: props.userName ?? null, - userAvatar: props.userAvatar ?? null, - showAvatarGutter: !isDirectThread, - contextWindow: threadContextWindow, - onReply: props.onSetReply - ? (target) => state.transcriptRenderContext.onSetReply?.(target) - : undefined, - resolveReplyPreview, - onResolveReply: props.replyMessageAccess?.request, - onOpenReply: (replyToId: string) => state.transcriptRenderContext.onOpenReply?.(replyToId), - replyNavigationId: props.replyMessageAccess?.navigationId, - onRewind: - rewindEntryId && props.onRewindMessage - ? () => { - void Promise.resolve(props.onRewindMessage?.(rewindEntryId)).then((rewound) => { - if (rewound) { - props.onFocusComposer?.(); - } - }); - } - : undefined, - rewindDisabled: Boolean(props.runActive || props.runWorking), - activeContinuation: activeContinuationByGroupKey.get(item.key), - turnRecap: turnRecapByGroupKey.get(item.key), - } satisfies Parameters[1]; - }; - const renderGroupItem = (item: MessageGroup) => { - return renderMessageGroup(item, renderGroupOptions(item)); - }; - // Only the working indicator shows live usage, so rows without one keep - // memoizing across usage patches. - const workingUsageKey = `usage:${props.runOutputTokens ?? ""}`; - const liveStatusSignature = (item: ChatRenderItem): string => { - if (item.kind === "stream-run") { - return item.parts.some((part) => part.kind === "reading-indicator") ? workingUsageKey : ""; - } - if (item.kind !== "group") { - return ""; - } - const continuation = activeContinuationByGroupKey.get(item.key); - const recap = turnRecapByGroupKey.get(item.key); - // Part keys stand in for the rest of the continuation: its remaining - // options mirror props that already invalidate every row through the - // shared render context. - const continuationKey = continuation - ? `${continuation.parts.map((part) => part.key).join(" ")}${workingUsageKey}` - : ""; - const recapKey = recap ? `${recap.runtimeMs}:${recap.outputTokens ?? ""}` : ""; - return `${continuationKey}|${recapKey}`; - }; - const renderItem = guardChatRenderItems(state, liveStatusSignature, (item) => { - if (item.kind === "divider") { - return renderChatDivider(item, props.onOpenSessionCheckpoints); - } - if (item.kind === "notice") { - return renderChatNotice(item); - } - if (item.kind === "stream-run") { - return renderStreamGroup(item.parts, { - ...streamGroupOptions, - questionPrompts, - planStatus: props.planStatus, - planActive: Boolean(props.runActive), - startupPhase: props.startupStatus?.phase, - waitingApproval: props.waitingApproval, - runOutputTokens: props.runOutputTokens, - }); - } - if (item.kind === "work-group") { - const workExpanded = expandedToolCards.get(item.key) ?? item.hasError; - return html` - ${renderWorkGroupSummary(item, { - expanded: workExpanded, - onToggle: () => { - setExpansionState(expandedToolCards, item.key, !workExpanded); - requestUpdate(); - }, - })} - ${workExpanded ? item.groups.map((group) => renderGroupItem(group)) : nothing} - `; - } - if (item.kind === "activity-run") { - const firstGroup = item.groups[0]; - if (!firstGroup) { - return nothing; - } - if (item.groups.length === 1) { - return renderGroupItem(firstGroup); - } - return renderActivityGroup(item.groups, renderGroupOptions(firstGroup)); - } - if (item.kind === "group") { - return renderGroupItem(item); - } - if (item.kind === "question") { - return renderStreamGroup([item], { - questionPrompts, - }); - } - return nothing; - }); - const collapsedItems = coalesceActivityRuns( - collapseCompletedTurnWork(coalesceStreamRuns(chatItems), { - sessionKey: props.sessionKey, - runWorking: Boolean(props.runWorking), - searchActive: searchFiltering, - }), - { searchActive: searchFiltering }, - ); - // Watch/settle on actual indicator visibility (not runWorking): queued - // sends show the claw before the run starts, and the recap must never - // stack under a visible working row. - const workingIndicatorVisible = chatItems.some((item) => item.kind === "reading-indicator"); - const turnRecap = resolveTurnRecap(props.sessionKey, workingIndicatorVisible, activeSession); - const transcriptItems = collapsedItems.filter((item, index) => { - if (item.kind !== "stream-run") { - return true; - } - const previous = collapsedItems[index - 1]; - const isActiveStatusRun = - item.parts.some((part) => part.kind === "reading-indicator") && - item.parts.every((part) => part.kind === "reading-indicator" || part.kind === "plan"); - if ( - previous?.kind !== "group" || - !isActiveStatusRun || - !assistantGroupCanOwnActiveRunStatus(previous) - ) { - return true; - } - // A reply and its still-running state are one turn-level presentation. - // Keeping the status in the reply avoids a second claw/assistant row. - activeContinuationByGroupKey.set(previous.key, { - parts: item.parts, - options: { - ...streamGroupOptions, - planStatus: props.planStatus, - planActive: Boolean(props.runActive), - startupPhase: props.startupStatus?.phase, - waitingApproval: props.waitingApproval, - runOutputTokens: props.runOutputTokens, - }, - }); - return false; - }); - for (const item of transcriptItems) { - if (item.kind !== "group") { - continue; - } - const senderLabel = resolveMessageGroupSenderLabel(item, { - assistantName: props.assistantName, - userId: props.userId, - userName: props.userName, - userAvatar: props.userAvatar, - }); - for (const source of item.messages) { - const sourceMessageId = persistedMessageEntryId(source.message); - const text = resolveMessageReplyText(source.message); - if (sourceMessageId && text) { - loadedReplySources.set(sourceMessageId, { - rowKey: item.key, - preview: { - messageId: source.key, - sourceMessageId, - senderLabel, - text, - }, - }); - } - } - } - transcript.syncMessageRows( - new Map([...loadedReplySources].map(([messageId, source]) => [messageId, source.rowKey])), - ); - let turnRecapOwnerKey: string | null = null; - if (turnRecap !== null) { - const lastItem = transcriptItems.at(-1); - if (lastItem?.kind === "group" && assistantGroupCanOwnActiveRunStatus(lastItem)) { - turnRecapByGroupKey.set(lastItem.key, turnRecap); - turnRecapOwnerKey = lastItem.key; - } - } - const transcriptRows: ChatTranscriptRow[] = transcriptItems.map((item) => ({ - kind: "item", - key: item.key, - item, - })); - const realtimeConversation = renderRealtimeTalkConversation(props); - if (realtimeConversation !== nothing) { - transcriptRows.push({ - kind: "content", - key: "realtime-talk", - content: realtimeConversation, - }); - } - if (turnRecap !== null && turnRecapOwnerKey === null && !isEmpty && !showLoadingSkeleton) { - transcriptRows.push({ - kind: "content", - key: "turn-recap", - content: renderTurnRecapRow(turnRecap), - }); - } - const backgroundTasks = - !props.runWorking && !isEmpty && !showLoadingSkeleton - ? renderBackgroundTasksStatusRow(props.backgroundTasks) - : nothing; - if (backgroundTasks !== nothing) { - transcriptRows.push({ - kind: "content", - key: "background-tasks", - content: backgroundTasks, - }); - } - trackTranscriptRenderDependencies(state, [ - chatItems, - locale, - expandedToolCards, - getExpansionStateVersion(expandedToolCards), - expandedUserMessages, - getExpansionStateVersion(expandedUserMessages), - assistantMessageExpansionSignature(expandedAssistantMessages), - getChatMediaRenderVersion(), - // The host minute poll requests an update; this key crosses row guard() memoization. - Math.floor(Date.now() / 60_000), - getToolTitlesVersion(), - props.sessionKey, - props.gatewayUrl, - props.boardProvider, - props.boardProvider?.canPinWidgets, - props.boardProvider?.canPinMcpApps, - props.boardProvider?.snapshot$.value.revision, - props.fullMessageAgentId, - Boolean(props.loadFullAssistantMessage), - showReasoning, - props.showToolCalls, - Boolean(props.runActive), - Boolean(props.runWorking), - props.startupStatus?.phase, - Boolean(props.waitingApproval), - props.planStatus, - props.questionPrompts, - Boolean(props.autoExpandToolCalls), - props.assistantName, - assistantIdentity.avatar, - props.userId, - props.userName, - props.userAvatar, - props.basePath, - (props.localMediaPreviewRoots ?? []).join("\u0000"), - props.assistantAttachmentAuthToken, - props.canvasPluginSurfaceUrl, - props.embedSandboxMode ?? "scripts", - props.allowExternalEmbedUrls ?? false, - threadContextWindow, - Boolean(props.onSetReply), - props.replyMessageAccess?.revision ?? 0, - props.replyMessageAccess?.navigationId ?? "", - turnRecap === null ? "" : `${turnRecap.runtimeMs}:${turnRecap.outputTokens ?? ""}`, - ]); - state.transcriptRenderContext.onSetReply = props.onSetReply; - state.transcriptRenderContext.onOpenReply = (replyToId) => { - if (loadedReplySources.has(replyToId)) { - transcript.revealMessage(replyToId); - return; - } - if (searchFiltering) { - closeChatThreadSearch(state, requestUpdate); - } - props.replyMessageAccess?.open(replyToId); - }; + const projection = projectChatTranscript(props, transcript); const transcriptContents = - showLoadingSkeleton || isEmpty + projection.showLoadingSkeleton || projection.isEmpty ? html`
${props.historyPagination ? renderHistorySentinel(props.historyPagination.loading) : nothing} - ${showLoadingSkeleton ? renderLoadingSkeleton() : nothing} - ${isEmpty && !state.searchOpen ? renderWelcomeState(props) : nothing} - ${isEmpty && state.searchOpen + ${projection.showLoadingSkeleton ? renderLoadingSkeleton() : nothing} + ${projection.isEmpty && !projection.searchOpen ? renderWelcomeState(props) : nothing} + ${projection.isEmpty && projection.searchOpen ? html`
${t("chat.thread.noMatches")}
` : nothing}
` - : transcript.render( - transcriptRows, - (row) => (row.kind === "item" ? renderItem(row.item) : row.content), - latestTranscriptAnnouncement(collapsedItems), - props.announceTranscript !== false && !state.searchOpen && !props.loading, + : projection.renderRows( props.historyPagination ? renderHistorySentinel(props.historyPagination.loading) : nothing, ); return html`
handleChatContextMenu(event, props)} - @pointerup=${(event: PointerEvent) => handleChatThreadSelectionPointerUp(event, props)} + @contextmenu=${(event: MouseEvent) => handleTranscriptContextMenu(event, props)} + @pointerup=${(event: PointerEvent) => handleTranscriptSelection(event, props)} > `; } -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/ui/src/pages/chat/components/chat-transcript-controller.test.ts b/ui/src/pages/chat/components/chat-transcript-controller.test.ts new file mode 100644 index 000000000000..ee405b099f38 --- /dev/null +++ b/ui/src/pages/chat/components/chat-transcript-controller.test.ts @@ -0,0 +1,197 @@ +/* @vitest-environment jsdom */ + +import { render } from "lit"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createTestTranscript } from "../chat-view.test-helpers.ts"; +import { renderChatThread } from "./chat-thread.ts"; +import { + flushDeferredRowPrune, + installTranscriptDomMocks, + observedElements, + resetTranscriptTestDom, + resizeObservers, + threadProps, + transcriptDomState, + transcriptRows, +} from "./chat-transcript.test-support.ts"; + +describe("chat transcript controller", () => { + beforeEach(installTranscriptDomMocks); + afterEach(resetTranscriptTestDom); + + it("keeps every re-stamped row observed after moving containers", async () => { + const transcript = createTestTranscript(); + const props = threadProps("pane-measure"); + const chatFace = document.body.appendChild(document.createElement("div")); + render(renderChatThread(props, transcript), chatFace); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const chatRows = transcriptRows(chatFace); + expect(chatRows.length).toBeGreaterThanOrEqual(4); + for (const row of chatRows) { + expect(observedElements.has(row)).toBe(true); + } + + // Re-stamp the same session transcript into a new container while the old + // tree is still tracked, mirroring the dashboard face-switch commit. + const dashboardDock = document.body.appendChild(document.createElement("div")); + render(renderChatThread(props, transcript), dashboardDock); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const dockRows = transcriptRows(dashboardDock); + expect(dockRows.length).toBe(chatRows.length); + for (const row of dockRows) { + expect(observedElements.has(row)).toBe(true); + } + for (const row of chatRows) { + expect(observedElements.has(row)).toBe(false); + } + }); + + it("pauses an unmeasurable restore until loading commits an empty transcript", () => { + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const props = threadProps("pane-loading-scroll", "agent:main:session-a", []); + render(renderChatThread({ ...props, loading: true }, transcript), container); + transcript.hostConnected(); + transcript.hostUpdated(); + transcript.scrollToOffset(420); + transcript.hostUpdated(); + + expect(transcript.pendingScrollOffsetFor(props.sessionKey)).toBe(420); + + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + expect(transcript.pendingScrollOffsetFor(props.sessionKey)).toBeNull(); + }); + + it("settles a restored offset when loaded rows no longer overflow", () => { + const frames: FrameRequestCallback[] = []; + vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => { + frames.push(callback); + return frames.length; + }); + vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => undefined); + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const props = threadProps("pane-short-scroll", "agent:main:session-a"); + render(renderChatThread(props, transcript), container); + transcript.hostConnected(); + transcript.hostUpdated(); + transcript.scrollToOffset(420); + + for (let index = 0; index <= 60; index += 1) { + transcript.hostUpdated(); + for (const frame of frames.splice(0)) { + frame(0); + } + } + + expect(transcript.pendingScrollOffsetFor(props.sessionKey)).toBeNull(); + }); + + it("updates rendered row offsets from freshly wrapped heights while scrolling", async () => { + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const props = threadProps("pane-width-remeasure"); + const renderTranscript = async () => { + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + }; + + await renderTranscript(); + transcript.hostConnected(); + await renderTranscript(); + expect(transcriptRows(container)[1]?.style.transform).toBe("translateY(100px)"); + + const scrollElement = container.querySelector(".chat-thread"); + expect(scrollElement).not.toBeNull(); + scrollElement!.scrollTop = 40; + scrollElement!.dispatchEvent(new Event("scroll")); + const virtualizer = ( + transcript as unknown as { + sessionVirtualizer: { + virtualizerController: { getVirtualizer: () => { isScrolling: boolean } }; + }; + } + ).sessionVirtualizer.virtualizerController.getVirtualizer(); + expect(virtualizer.isScrolling).toBe(true); + + transcriptDomState.measuredRowHeight = 180; + for (const observer of resizeObservers) { + if (scrollElement && observer.observes(scrollElement)) { + observer.emit(640, 600); + } + } + await renderTranscript(); + + expect(transcriptRows(container)[1]?.style.transform).toBe("translateY(180px)"); + transcript.hostDisconnected(); + }); + + it.each([ + { label: "end-pinned", distanceFromEnd: 0, expectedCalls: 1 }, + { label: "scrolled away", distanceFromEnd: 100, expectedCalls: 0 }, + ])( + "$label transcript preserves its resize anchor", + async ({ distanceFromEnd, expectedCalls }) => { + transcriptDomState.measuredRowHeight = 240; + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const messages = Array.from({ length: 12 }, (_, index) => ({ + role: index % 2 === 0 ? "user" : "assistant", + content: `message ${index}`, + timestamp: index + 1, + })); + const props = threadProps( + `pane-height-resize-${distanceFromEnd}`, + "agent:main:resize", + messages, + ); + render(renderChatThread(props, transcript), container); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const scrollElement = container.querySelector(".chat-thread"); + expect(scrollElement).not.toBeNull(); + const virtualizer = ( + transcript as unknown as { + sessionVirtualizer: { + virtualizerController: { + getVirtualizer: () => { + scrollOffset: number | null; + getTotalSize: () => number; + scrollToEnd: (options?: { behavior?: ScrollBehavior }) => void; + }; + }; + }; + } + ).sessionVirtualizer.virtualizerController.getVirtualizer(); + const scrollToEnd = vi.spyOn(virtualizer, "scrollToEnd"); + const emitViewportResize = (height: number) => { + for (const observer of resizeObservers) { + if (scrollElement && observer.observes(scrollElement)) { + observer.emit(800, height); + } + } + }; + + emitViewportResize(600); + scrollToEnd.mockClear(); + expect(virtualizer.getTotalSize()).toBeGreaterThan(700); + virtualizer.scrollOffset = Math.max(0, virtualizer.getTotalSize() - 600 - distanceFromEnd); + emitViewportResize(560); + + expect(scrollToEnd).toHaveBeenCalledTimes(expectedCalls); + if (expectedCalls > 0) { + expect(scrollToEnd).toHaveBeenCalledWith({ behavior: "auto" }); + } + transcript.hostDisconnected(); + }, + ); +}); diff --git a/ui/src/pages/chat/components/chat-transcript-controller.ts b/ui/src/pages/chat/components/chat-transcript-controller.ts new file mode 100644 index 000000000000..6981503daf28 --- /dev/null +++ b/ui/src/pages/chat/components/chat-transcript-controller.ts @@ -0,0 +1,670 @@ +// Session-owned virtualizer lifecycle for chat transcripts. +import { VirtualizerController } from "@tanstack/lit-virtual"; +import { defaultRangeExtractor, observeElementRect } from "@tanstack/virtual-core"; +import { + html, + nothing, + type ReactiveController, + type ReactiveControllerHost, + type TemplateResult, +} from "lit"; +import { ref } from "lit/directives/ref.js"; +import { repeat } from "lit/directives/repeat.js"; +import { styleMap } from "lit/directives/style-map.js"; +import { McpAppUnmountGate } from "../../../components/mcp-app-unmount.ts"; +import { areUiSessionKeysEquivalent } from "../../../lib/sessions/session-key.ts"; +import { + CHAT_TRANSCRIPT_END_THRESHOLD_PX, + getChatSessionScrollPosition, + saveChatSessionScrollPosition, + type ChatSessionScrollPosition, +} from "../scroll.ts"; + +export type TranscriptRow = + | { kind: "item"; key: string; item: T } + | { kind: "content"; key: string; content: unknown }; + +export type TranscriptAnnouncement = { + key: string; + text: string; +}; + +export type ChatTranscriptSession = { + readonly liveAnnouncementText: string; + render( + rows: readonly TranscriptRow[], + renderRow: (row: TranscriptRow) => unknown, + announcement: TranscriptAnnouncement | null, + announce: boolean, + overlay?: unknown, + ): TemplateResult; + syncMessageRows(messageRowKeysById: ReadonlyMap): void; + revealMessage(messageId: string): boolean; + setContentReady(ready: boolean): void; + handleFocusIn(event: FocusEvent): void; + handleFocusOut(event: FocusEvent): void; +}; + +const CHAT_TRANSCRIPT_ESTIMATED_ROW_PX = 120; +const CHAT_TRANSCRIPT_OVERSCAN = 6; +// Initial virtual rows can correct their estimates for several frames. Hold a +// restored offset for ~200ms so those corrections cannot reapply the end anchor. +const CHAT_TRANSCRIPT_SCROLL_RESTORE_STABLE_FRAMES = 12; +// A committed short transcript can legitimately remain at maxOffset=0. Give +// initial measurement one second before treating that zero range as final. +const CHAT_TRANSCRIPT_ZERO_MAX_SETTLE_FRAMES = 60; +function initialTranscriptRect(host: ReactiveControllerHost) { + const width = host instanceof HTMLElement ? host.clientWidth : 0; + const height = host instanceof HTMLElement ? host.clientHeight : 0; + return { + width: width || (typeof window === "undefined" ? 0 : window.innerWidth), + height: height || (typeof window === "undefined" ? 0 : window.innerHeight), + }; +} + +function transcriptScrollMargin(element: Element | null): number { + if (!(element instanceof HTMLElement) || typeof getComputedStyle !== "function") { + return 0; + } + const margin = Number.parseFloat(getComputedStyle(element).paddingTop); + return Number.isFinite(margin) ? margin : 0; +} + +function initialTranscriptScrollMargin(host: ReactiveControllerHost): number { + return host instanceof HTMLElement + ? transcriptScrollMargin(host.querySelector(".chat-thread")) + : 0; +} + +class ChatSessionVirtualizerHost implements ReactiveControllerHost, ChatTranscriptSession { + private readonly controllers = new Set(); + private readonly virtualizerController: VirtualizerController; + private threadInnerElement: HTMLDivElement | null = null; + private connected = false; + private observedWidth: number | null = null; + private observedHeight: number | null = null; + private contentReady = false; + private pendingScrollOffset: { + offset: number; + stableFrames: number; + zeroMaxFrames: number; + onSettled?: (position: ChatSessionScrollPosition) => void; + } | null = null; + private pendingScrollFrame: number | null = null; + // Lit calls refs before newly rendered nodes are connected. Resolve the + // scroll parent lazily or a stable ref can permanently capture null. + private get scrollElement(): HTMLDivElement | null { + const parent = this.threadInnerElement?.parentElement; + return parent instanceof HTMLDivElement ? parent : null; + } + // Stable Lit refs: inline arrows change identity per render, making Lit + // re-invoke them for every visible row and re-measure each row every render. + // Lit tracks the last element per callback, so each row needs its own. + private readonly scrollElementRef = (element?: Element) => { + this.threadInnerElement = element instanceof HTMLDivElement ? element : null; + }; + private readonly measureRowRefs = new Map void>(); + private pruneDetachedRowsQueued = false; + private pendingRowMeasureFrame: number | null = null; + private measureConnectedRows(): void { + // Only width invalidation owns forced DOM reads. Ordinary row refs stay on + // TanStack's observer path so resizeItem cannot perturb scroll restoration. + const instance = this.virtualizerController.getVirtualizer(); + for (const row of this.threadInnerElement?.querySelectorAll(".chat-virtual-row") ?? + []) { + instance.resizeItem( + instance.indexFromElement(row), + row[instance.options.horizontal ? "offsetWidth" : "offsetHeight"], + ); + } + } + private queueConnectedRowMeasure(): void { + if (this.pendingRowMeasureFrame !== null) { + return; + } + this.pendingRowMeasureFrame = requestAnimationFrame(() => { + this.pendingRowMeasureFrame = null; + this.measureConnectedRows(); + }); + } + private measureRowRefFor(key: string): (element?: Element) => void { + let callback = this.measureRowRefs.get(key); + if (!callback) { + callback = (element?: Element) => { + if (element instanceof HTMLElement) { + this.virtualizerController.getVirtualizer().measureElement(element); + return; + } + // Re-stamps (e.g. the chat<->dashboard face switch) re-invoke each + // stable row ref as an (undefined, element) pair while the new subtree + // is still detached. measureElement(null) prunes every disconnected + // row, so calling it synchronously unobserves just-registered sibling + // rows and freezes their heights at the old pane width (overlapping + // bubbles). Defer until the commit lands so only removed rows prune. + if (this.pruneDetachedRowsQueued) { + return; + } + this.pruneDetachedRowsQueued = true; + queueMicrotask(() => { + this.pruneDetachedRowsQueued = false; + this.virtualizerController.getVirtualizer().measureElement(null); + }); + }; + this.measureRowRefs.set(key, callback); + } + return callback; + } + private rowKeys: readonly string[] = []; + private rowIndexesByKey = new Map(); + private messageRowKeysById = new Map(); + private focusedRowKey: string | null = null; + private announcementInitialized = false; + private announcementKey: string | null = null; + private currentAnnouncementText = ""; + private readonly mcpAppUnmountGate = new McpAppUnmountGate(this); + + constructor( + private readonly host: ReactiveControllerHost, + initialOffset: number | null = null, + onInitialOffsetSettled?: (position: ChatSessionScrollPosition) => void, + ) { + this.virtualizerController = new VirtualizerController(this, { + count: 0, + getScrollElement: () => this.scrollElement, + estimateSize: () => CHAT_TRANSCRIPT_ESTIMATED_ROW_PX, + getItemKey: () => "", + initialRect: initialTranscriptRect(host), + initialOffset: initialOffset ?? Number.MAX_SAFE_INTEGER, + scrollMargin: initialTranscriptScrollMargin(host), + anchorTo: "end", + followOnAppend: false, + observeElementRect: (instance, callback) => + observeElementRect(instance, (rect) => { + const previousHeight = this.observedHeight; + const widthChanged = this.observedWidth !== null && this.observedWidth !== rect.width; + const heightChanged = previousHeight !== null && previousHeight !== rect.height; + const scrollOffset = instance.scrollOffset; + const wasAtEndBeforeResize = + heightChanged && + this.pendingScrollOffset === null && + scrollOffset !== null && + instance.getTotalSize() - previousHeight - scrollOffset <= + CHAT_TRANSCRIPT_END_THRESHOLD_PX; + this.observedWidth = rect.width; + this.observedHeight = rect.height; + this.syncScrollMargin(instance.scrollElement); + callback(rect); + if (wasAtEndBeforeResize) { + instance.scrollToEnd({ behavior: "auto" }); + } + if (widthChanged) { + // Cached offscreen sizes belong to the old wrapping width. Reset + // them, seed current rows, then repeat after any same-commit + // re-stamp has attached and completed layout. + instance.measure(); + this.measureConnectedRows(); + this.queueConnectedRowMeasure(); + } + }), + rangeExtractor: (range) => { + const indexes = defaultRangeExtractor(range); + const focused = + this.focusedRowKey === null ? undefined : this.rowIndexesByKey.get(this.focusedRowKey); + if ( + focused === undefined || + focused < 0 || + focused >= range.count || + indexes.includes(focused) + ) { + return indexes; + } + return [...indexes, focused].toSorted((left, right) => left - right); + }, + scrollEndThreshold: CHAT_TRANSCRIPT_END_THRESHOLD_PX, + overscan: CHAT_TRANSCRIPT_OVERSCAN, + }); + if (initialOffset !== null) { + this.pendingScrollOffset = { + offset: initialOffset, + stableFrames: 0, + zeroMaxFrames: 0, + onSettled: onInitialOffsetSettled, + }; + } + } + + get updateComplete() { + return this.host.updateComplete; + } + + get liveAnnouncementText() { + return this.currentAnnouncementText; + } + + requestUpdate = () => { + this.host.requestUpdate(); + }; + + addController(controller: ReactiveController): void { + this.controllers.add(controller); + } + + removeController(controller: ReactiveController): void { + this.controllers.delete(controller); + } + + connect(): void { + if (this.connected) { + return; + } + this.connected = true; + for (const controller of this.controllers) { + controller.hostConnected?.(); + } + if (this.pendingScrollOffset) { + this.host.requestUpdate(); + } + } + + update(): void { + for (const controller of this.controllers) { + controller.hostUpdated?.(); + } + this.applyPendingScrollOffset(); + } + + disconnect(): void { + if (this.pendingRowMeasureFrame !== null) { + cancelAnimationFrame(this.pendingRowMeasureFrame); + this.pendingRowMeasureFrame = null; + } + if (this.pendingScrollFrame !== null) { + cancelAnimationFrame(this.pendingScrollFrame); + this.pendingScrollFrame = null; + } + if (!this.connected) { + this.threadInnerElement = null; + return; + } + this.connected = false; + for (const controller of this.controllers) { + controller.hostDisconnected?.(); + } + this.threadInnerElement = null; + } + + dispose(): void { + this.disconnect(); + this.measureRowRefs.clear(); + this.rowKeys = []; + this.rowIndexesByKey.clear(); + this.messageRowKeysById.clear(); + this.focusedRowKey = null; + this.pendingScrollOffset = null; + } + + render( + rows: readonly TranscriptRow[], + renderRow: (row: TranscriptRow) => unknown, + announcement: TranscriptAnnouncement | null, + announce: boolean, + overlay: unknown = nothing, + ): TemplateResult { + this.syncRows(rows); + this.syncAnnouncement(announcement, announce); + const virtualizer = this.virtualizerController.getVirtualizer(); + const virtualRows = virtualizer.getVirtualItems(); + const nextRowKeys = new Set( + virtualRows.flatMap((virtualRow) => { + const row = rows[virtualRow.index]; + return row ? [row.key] : []; + }), + ); + const rendered = html` +
+
+ ${overlay} + ${repeat( + virtualRows, + (virtualRow) => virtualRow.key, + (virtualRow) => { + const row = rows[virtualRow.index]; + if (!row) { + return nothing; + } + return html` +
+ ${renderRow(row)} +
+ `; + }, + )} +
+
+ `; + return this.mcpAppUnmountGate.render(JSON.stringify([...nextRowKeys]), rendered, () => + this.threadInnerElement + ? [...this.threadInnerElement.querySelectorAll(".chat-virtual-row")].filter( + (row) => !nextRowKeys.has(row.dataset.virtualRowKey ?? ""), + ) + : [], + ) as TemplateResult; + } + + scrollToEnd(options: { behavior?: ScrollBehavior } = {}): void { + this.virtualizerController.getVirtualizer().scrollToEnd(options); + } + + scrollToOffset(offset: number): void { + if (this.scrollElement) { + this.scrollElement.scrollTop = offset; + } + this.virtualizerController.getVirtualizer().scrollToOffset(offset); + } + + syncMessageRows(messageRowKeysById: ReadonlyMap): void { + this.messageRowKeysById = new Map(messageRowKeysById); + } + + revealMessage(messageId: string): boolean { + const rowKey = this.messageRowKeysById.get(messageId); + if (!rowKey) { + return false; + } + const rowIndex = this.rowIndexesByKey.get(rowKey); + if (rowIndex === undefined) { + return false; + } + this.virtualizerController.getVirtualizer().scrollToIndex(rowIndex, { align: "center" }); + this.host.requestUpdate(); + void this.host.updateComplete.then(() => { + const bubble = [ + ...(this.threadInnerElement?.querySelectorAll(".chat-bubble") ?? []), + ].find((candidate) => candidate.dataset.entryId === messageId); + if (!bubble) { + return; + } + this.threadInnerElement + ?.querySelector(".chat-bubble--reply-target") + ?.classList.remove("chat-bubble--reply-target"); + bubble.scrollIntoView?.({ behavior: "smooth", block: "center" }); + bubble.classList.add("chat-bubble--reply-target"); + bubble.addEventListener( + "animationend", + () => bubble.classList.remove("chat-bubble--reply-target"), + { once: true }, + ); + }); + return true; + } + + getScrollOffset(): number | null { + return this.scrollElement?.scrollTop ?? null; + } + + getMaxScrollOffset(): number | null { + const scrollElement = this.scrollElement; + return scrollElement + ? Math.max(0, scrollElement.scrollHeight - scrollElement.clientHeight) + : null; + } + + setContentReady(ready: boolean): void { + this.contentReady = ready; + } + + restoreScrollOffset( + offset: number, + onSettled?: (position: ChatSessionScrollPosition) => void, + ): void { + this.pendingScrollOffset = { offset, stableFrames: 0, zeroMaxFrames: 0, onSettled }; + if (this.connected) { + this.host.requestUpdate(); + } + } + + getPendingScrollOffset(): number | null { + return this.pendingScrollOffset?.offset ?? null; + } + + handleFocusIn(event: FocusEvent): void { + this.focusedRowKey = this.rowKeyFromEvent(event); + } + + handleFocusOut(event: FocusEvent): void { + this.focusedRowKey = this.rowKeyFromEvent(event, event.relatedTarget); + } + + private rowKeyFromEvent(event: FocusEvent, target: EventTarget | null = event.target) { + if (!(target instanceof Element) || !this.scrollElement?.contains(target)) { + return null; + } + const row = target.closest(".chat-virtual-row[data-virtual-row-key]"); + if (!row || !this.scrollElement.contains(row)) { + return null; + } + return row.dataset.virtualRowKey || null; + } + + private syncAnnouncement(announcement: TranscriptAnnouncement | null, announce: boolean): void { + if (!this.announcementInitialized || !announce) { + this.announcementInitialized = true; + this.announcementKey = announcement?.key ?? null; + this.currentAnnouncementText = ""; + return; + } + if (!announcement || announcement.key === this.announcementKey) { + return; + } + this.announcementKey = announcement.key; + this.currentAnnouncementText = announcement.text; + } + + private syncRows(rows: readonly TranscriptRow[]): void { + const nextKeys = rows.map((row) => row.key); + if ( + nextKeys.length === this.rowKeys.length && + nextKeys.every((key, index) => key === this.rowKeys[index]) + ) { + return; + } + this.rowKeys = Object.freeze(nextKeys); + this.rowIndexesByKey = new Map(this.rowKeys.map((key, index) => [key, index])); + for (const key of this.measureRowRefs.keys()) { + if (!this.rowIndexesByKey.has(key)) { + this.measureRowRefs.delete(key); + } + } + const keys = this.rowKeys; + const virtualizer = this.virtualizerController.getVirtualizer(); + virtualizer.setOptions({ + ...virtualizer.options, + count: keys.length, + getItemKey: (index) => keys[index] ?? `missing:${index}`, + }); + } + + private syncScrollMargin(scrollElement: HTMLDivElement | null): void { + const scrollMargin = transcriptScrollMargin(scrollElement); + const virtualizer = this.virtualizerController.getVirtualizer(); + if (scrollMargin === virtualizer.options.scrollMargin) { + return; + } + virtualizer.setOptions({ + ...virtualizer.options, + scrollMargin, + }); + } + + private applyPendingScrollOffset(): void { + const pending = this.pendingScrollOffset; + if (!pending || !this.connected) { + return; + } + const maxOffset = this.getMaxScrollOffset(); + if (maxOffset === null) { + if (this.contentReady && this.rowKeys.length === 0) { + this.settlePendingScroll(0); + } + return; + } + if (maxOffset === 0 && pending.offset > 0) { + if (this.contentReady && this.rowKeys.length === 0) { + this.settlePendingScroll(0); + } else if (this.contentReady) { + if (pending.zeroMaxFrames >= CHAT_TRANSCRIPT_ZERO_MAX_SETTLE_FRAMES) { + this.settlePendingScroll(0); + return; + } + pending.zeroMaxFrames += 1; + this.schedulePendingScrollRetry(); + } + return; + } + pending.zeroMaxFrames = 0; + const targetOffset = Math.min(pending.offset, maxOffset); + this.scrollToOffset(targetOffset); + const currentOffset = this.getScrollOffset(); + if (currentOffset != null && Math.abs(currentOffset - targetOffset) <= 1) { + if (pending.stableFrames >= CHAT_TRANSCRIPT_SCROLL_RESTORE_STABLE_FRAMES) { + this.settlePendingScroll(currentOffset); + } else { + pending.stableFrames += 1; + this.schedulePendingScrollRetry(); + } + } else { + pending.stableFrames = 0; + this.schedulePendingScrollRetry(); + } + } + + private schedulePendingScrollRetry(): void { + if (!this.connected || this.pendingScrollFrame !== null) { + return; + } + this.pendingScrollFrame = requestAnimationFrame(() => { + this.pendingScrollFrame = null; + if (this.connected && this.pendingScrollOffset) { + this.host.requestUpdate(); + } + }); + } + + private settlePendingScroll(scrollTop: number): void { + const pending = this.pendingScrollOffset; + this.pendingScrollOffset = null; + if (!pending) { + return; + } + const maxScrollTop = this.getMaxScrollOffset(); + pending.onSettled?.({ + scrollTop, + anchorToEnd: + maxScrollTop === null + ? this.contentReady && this.rowKeys.length === 0 + : maxScrollTop - scrollTop <= CHAT_TRANSCRIPT_END_THRESHOLD_PX, + }); + } +} + +export class ChatTranscriptController implements ReactiveController { + private activeSessionKey: string | null = null; + private sessionVirtualizer: ChatSessionVirtualizerHost | null = null; + private connected = false; + + constructor(private readonly host: ReactiveControllerHost) { + host.addController(this); + } + + get renderedSessionKey(): string | null { + return this.activeSessionKey; + } + + renderSession( + paneId: string, + sessionKey: string, + render: (transcript: ChatTranscriptSession) => TemplateResult, + ): TemplateResult { + if ( + !this.sessionVirtualizer || + this.activeSessionKey === null || + !areUiSessionKeysEquivalent(this.activeSessionKey, sessionKey) + ) { + this.sessionVirtualizer?.dispose(); + const savedPosition = getChatSessionScrollPosition(paneId, sessionKey); + const initialOffset = savedPosition?.anchorToEnd ? null : (savedPosition?.scrollTop ?? null); + this.activeSessionKey = sessionKey; + this.sessionVirtualizer = new ChatSessionVirtualizerHost( + this.host, + initialOffset, + initialOffset === null + ? undefined + : (position) => { + saveChatSessionScrollPosition(paneId, sessionKey, position); + }, + ); + if (this.connected) { + this.sessionVirtualizer.connect(); + } + } + return render(this.sessionVirtualizer); + } + + scrollToEnd(options: { behavior?: ScrollBehavior } = {}): void { + this.sessionVirtualizer?.scrollToEnd(options); + } + + scrollToOffset(offset: number, onSettled?: (position: ChatSessionScrollPosition) => void): void { + this.sessionVirtualizer?.restoreScrollOffset(offset, onSettled); + } + + revealMessage(messageId: string): boolean { + return this.sessionVirtualizer?.revealMessage(messageId) ?? false; + } + + pendingScrollOffsetFor(sessionKey: string): number | null { + return this.activeSessionKey !== null && + areUiSessionKeysEquivalent(this.activeSessionKey, sessionKey) + ? (this.sessionVirtualizer?.getPendingScrollOffset() ?? null) + : null; + } + + handleFocusIn(event: FocusEvent): void { + this.sessionVirtualizer?.handleFocusIn(event); + } + + handleFocusOut(event: FocusEvent): void { + this.sessionVirtualizer?.handleFocusOut(event); + } + + hostConnected(): void { + this.connected = true; + this.sessionVirtualizer?.connect(); + } + + hostUpdated(): void { + this.sessionVirtualizer?.update(); + } + + hostDisconnected(): void { + this.connected = false; + this.sessionVirtualizer?.disconnect(); + } +} diff --git a/ui/src/pages/chat/components/chat-transcript-invalidation.test.ts b/ui/src/pages/chat/components/chat-transcript-invalidation.test.ts new file mode 100644 index 000000000000..3cae65d308eb --- /dev/null +++ b/ui/src/pages/chat/components/chat-transcript-invalidation.test.ts @@ -0,0 +1,507 @@ +/* @vitest-environment jsdom */ + +import { expectDefined } from "@openclaw/normalization-core"; +import { render } from "lit"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { BoardProvider } from "../../../lib/board/provider.ts"; +import { resolveAssistantAttachmentAuthToken } from "../chat-pane-state.ts"; +import { createTestChatPane } from "../chat-pane.test-support.ts"; +import * as chatThreadBuild from "../chat-thread-build.ts"; +import { + buildCachedChatItems, + getExpandedToolCards, + getExpandedUserMessages, + getExpansionStateVersion, +} from "../chat-thread.ts"; +import { createTestTranscript } from "../chat-view.test-helpers.ts"; +import { + isChatMediaResourceCurrent, + observeChatMediaResource, + releaseChatMediaResourceSubscriber, +} from "./chat-message-media.ts"; +import { resetTranscriptSession } from "./chat-thread-interactions.ts"; +import { renderChatThread } from "./chat-thread.ts"; +import { + flushDeferredRowPrune, + installTranscriptDomMocks, + resetTranscriptTestDom, + threadProps, +} from "./chat-transcript.test-support.ts"; + +describe("chat transcript invalidation", () => { + beforeEach(installTranscriptDomMocks); + afterEach(resetTranscriptTestDom); + + it("keeps built row identities across an A to B to A presentation reset", () => { + const paneId = "pane-session-items"; + const messagesA = [{ role: "assistant", content: "session A", timestamp: 1_000 }]; + const messagesB = [{ role: "assistant", content: "session B", timestamp: 2_000 }]; + const stableInputs = { + paneId, + runId: null, + toolMessages: [], + streamSegments: [], + stream: null, + streamStartedAt: null, + showToolCalls: true, + }; + const buildSpy = vi.spyOn(chatThreadBuild, "buildChatItems"); + const itemsA = buildCachedChatItems({ + ...stableInputs, + sessionKey: "agent:main:session-a", + messages: messagesA, + }); + + resetTranscriptSession(paneId); + buildCachedChatItems({ + ...stableInputs, + sessionKey: "agent:main:session-b", + messages: messagesB, + }); + resetTranscriptSession(paneId); + const restoredItemsA = buildCachedChatItems({ + ...stableInputs, + sessionKey: "agent:main:session-a", + messages: messagesA, + }); + + expect(buildSpy).toHaveBeenCalledTimes(2); + expect(restoredItemsA).toBe(itemsA); + expect(restoredItemsA.every((item, index) => item === itemsA[index])).toBe(true); + }); + + it("rebinds guarded transcript images when the gateway rotates its auth token", async () => { + const NativeUrl = URL; + const blobUrl = `blob:transcript-media-${crypto.randomUUID()}`; + vi.stubGlobal( + "URL", + class extends NativeUrl { + static override createObjectURL = vi.fn(() => blobUrl); + static override revokeObjectURL = vi.fn(); + }, + ); + + let previousSignal: AbortSignal | undefined; + const fetchMock = vi.fn((_source: string, init?: RequestInit) => { + if (fetchMock.mock.calls.length === 1) { + return new Promise((_resolve, reject) => { + previousSignal = init?.signal ?? undefined; + previousSignal?.addEventListener( + "abort", + () => reject(new DOMException("media scope changed", "AbortError")), + { once: true }, + ); + }); + } + return Promise.resolve({ + ok: true, + blob: async () => new Blob(["png"], { type: "image/png" }), + } as Response); + }); + vi.stubGlobal("fetch", fetchMock); + + const source = `/api/chat/media/outgoing/agent%3Amain%3Amain/${crypto.randomUUID()}/full`; + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const client = { + request: vi.fn(async () => null), + } as unknown as Parameters[0]["client"]; + const sessions = {} as Parameters[0]["sessions"]; + const { pane, state } = createTestChatPane({ client, sessions }); + state.hello = { + auth: { deviceToken: "test-auth-token" }, + } as typeof state.hello; + const messages = [ + { + role: "assistant", + content: [{ type: "image", url: source }], + timestamp: 1_000, + }, + ]; + const renderPane = () => { + render( + renderChatThread( + { + ...threadProps("pane-gateway-media-auth", state.sessionKey, messages), + assistantAttachmentAuthToken: resolveAssistantAttachmentAuthToken(state), + onRequestUpdate: renderPane, + }, + transcript, + ), + container, + ); + transcript.hostUpdated(); + }; + state.requestUpdate = renderPane; + + renderPane(); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const thumbnailSource = source.replace(/\/full$/u, "/thumbnail"); + const previousResource = observeChatMediaResource( + "managed-image", + `${thumbnailSource}::test-auth-token::`, + ); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(previousResource.subscribers.size).toBe(1); + + pane.applyGatewaySnapshot({ + ...pane.context.gateway.snapshot, + client, + phase: "connected", + hello: { + ...pane.context.gateway.snapshot.hello, + auth: { deviceToken: "test-token" }, + } as typeof pane.context.gateway.snapshot.hello, + }); + expect(previousSignal?.aborted).toBe(true); + expect(isChatMediaResourceCurrent(previousResource)).toBe(false); + await flushDeferredRowPrune(); + + const nextResource = observeChatMediaResource( + "managed-image", + `${thumbnailSource}::test-token::`, + ); + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(new Headers(fetchMock.mock.calls[1]?.[1]?.headers).get("Authorization")).toBe( + "Bearer test-token", + ); + expect(isChatMediaResourceCurrent(nextResource)).toBe(true); + expect(nextResource.subscribers.size).toBe(1); + expect(container.querySelector(".chat-message-image")?.src).toBe(blobUrl); + + releaseChatMediaResourceSubscriber(renderPane); + transcript.hostDisconnected(); + }); + + it("reconciles guarded local attachments when pane preview roots change", async () => { + let previousSignal: AbortSignal | undefined; + const fetchMock = vi.fn((_source: string, init?: RequestInit) => { + if (fetchMock.mock.calls.length === 1) { + return new Promise((_resolve, reject) => { + previousSignal = init?.signal ?? undefined; + previousSignal?.addEventListener( + "abort", + () => reject(new DOMException("preview roots changed", "AbortError")), + { once: true }, + ); + }); + } + return Promise.resolve({ + ok: true, + json: async () => ({ + available: true, + mediaTicket: "root-restored-ticket", + mediaTicketExpiresAt: new Date(Date.now() + 90_000).toISOString(), + }), + } as Response); + }); + vi.stubGlobal("fetch", fetchMock); + + const client = { + request: vi.fn(async () => null), + } as unknown as Parameters[0]["client"]; + const sessions = {} as Parameters[0]["sessions"]; + const { pane, state } = createTestChatPane({ client, sessions }); + const configPane = pane as typeof pane & { + applyApplicationConfig: (config: typeof pane.context.config.current) => void; + }; + state.hello = { + auth: { deviceToken: "test-auth-token" }, + } as typeof state.hello; + state.localMediaPreviewRoots = ["/tmp/openclaw"]; + state.embedSandboxMode = "scripts"; + state.allowExternalEmbedUrls = false; + + const source = `/tmp/openclaw/${crypto.randomUUID()}.pdf`; + const messages = [ + { + role: "assistant", + content: `Local document\nMEDIA:${source}`, + timestamp: 1_000, + }, + ]; + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const renderPane = () => { + render( + renderChatThread( + { + ...threadProps("pane-local-media-roots", state.sessionKey, messages), + assistantAttachmentAuthToken: resolveAssistantAttachmentAuthToken(state), + localMediaPreviewRoots: state.localMediaPreviewRoots, + onRequestUpdate: renderPane, + }, + transcript, + ), + container, + ); + transcript.hostUpdated(); + }; + state.requestUpdate = renderPane; + + renderPane(); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const previousResource = observeChatMediaResource( + "assistant-attachment", + `::test-auth-token::${source}`, + ); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(previousResource.subscribers.size).toBe(1); + + const config = { + ...pane.context.config.current, + localMediaPreviewRoots: ["/tmp/elsewhere"], + embedSandboxMode: "scripts" as const, + allowExternalEmbedUrls: false, + }; + configPane.applyApplicationConfig(config); + await flushDeferredRowPrune(); + + expect(previousSignal?.aborted).toBe(true); + expect(isChatMediaResourceCurrent(previousResource)).toBe(false); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect( + container.querySelector(".chat-assistant-attachment-card__reason")?.textContent, + ).toContain("Outside allowed folders"); + + configPane.applyApplicationConfig({ + ...config, + localMediaPreviewRoots: ["/tmp/openclaw"], + }); + await flushDeferredRowPrune(); + + const restoredResource = observeChatMediaResource( + "assistant-attachment", + `::test-auth-token::${source}`, + ); + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(new Headers(fetchMock.mock.calls[1]?.[1]?.headers).get("Authorization")).toBe( + "Bearer test-auth-token", + ); + expect(isChatMediaResourceCurrent(restoredResource)).toBe(true); + expect(restoredResource.subscribers.size).toBe(1); + expect( + container.querySelector(".chat-assistant-attachment-card__link")?.getAttribute("href"), + ).toContain("mediaTicket=root-restored-ticket"); + + releaseChatMediaResourceSubscriber(renderPane); + transcript.hostDisconnected(); + }); + + it("updates MCP App pinning when the same provider's capability changes", async () => { + const provider = { + sessionKey: "agent:main:main", + canPinWidgets: true, + canPinMcpApps: false, + pinMcpApp: vi.fn(async () => undefined), + snapshot$: { + value: { + sessionKey: "agent:main:main", + revision: 1, + tabs: [], + widgets: [], + }, + subscribe: () => () => undefined, + }, + }; + const props = { + ...threadProps("pane-mcp-capability"), + boardProvider: provider as unknown as BoardProvider, + messages: [ + { + role: "assistant", + timestamp: 1_000, + content: [ + { type: "text", text: "Here is the dashboard app." }, + { + type: "canvas", + preview: { + kind: "canvas", + surface: "assistant_message", + render: "url", + title: "Dashboard app", + viewId: "outer-view-must-not-be-pinned", + mcpApp: { + viewId: "view-dashboard-app", + serverName: "dashboard", + toolName: "show", + uiResourceUri: "ui://dashboard/app.html", + toolCallId: "call-dashboard-app", + originSessionKey: "agent:main:main", + }, + }, + }, + ], + }, + ], + }; + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + + render(renderChatThread(props, transcript), container); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + expect(container.querySelector('[data-content-kind="mcp-app"]')).not.toBeNull(); + expect(container.querySelector("[data-pin-widget]")).toBeNull(); + + provider.canPinMcpApps = true; + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + + expect(container.querySelector("[data-pin-widget]")).not.toBeNull(); + expect(provider.snapshot$.value.revision).toBe(1); + + provider.canPinMcpApps = false; + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + + expect(container.querySelector("[data-pin-widget]")).toBeNull(); + expect(provider.snapshot$.value.revision).toBe(1); + }); + + it("keeps mounted disclosure handlers attached to recreated session expansion maps", () => { + const sessionKey = "retained-session"; + const props = { + ...threadProps("retained-pane", sessionKey, [ + { role: "user", content: "long user message ".repeat(100), timestamp: 1 }, + { + role: "assistant", + content: [ + { type: "text", text: "assistant reply" }, + { type: "toolcall", id: "retained-call", name: "browser.open" }, + ], + timestamp: 2, + }, + ]), + showToolCalls: true, + }; + const controller = createTestTranscript(); + const retainedPane = document.body.appendChild(document.createElement("div")); + render(renderChatThread(props, controller), retainedPane); + const staleTools = getExpandedToolCards(sessionKey); + const staleUsers = getExpandedUserMessages(sessionKey); + const previousToolVersion = getExpansionStateVersion(staleTools); + const previousUserVersion = getExpansionStateVersion(staleUsers); + + for (let index = 0; index < 20; index += 1) { + const alternatePane = document.body.appendChild(document.createElement("div")); + render( + renderChatThread( + { + ...props, + paneId: `alternate-pane-${index}`, + sessionKey: `alternate-session-${index}`, + }, + createTestTranscript(), + ), + alternatePane, + ); + } + + render(renderChatThread(props, controller), retainedPane); + const currentTools = getExpandedToolCards(sessionKey); + const currentUsers = getExpandedUserMessages(sessionKey); + expect(currentTools).not.toBe(staleTools); + expect(currentUsers).not.toBe(staleUsers); + expect(getExpansionStateVersion(currentTools)).toBe(previousToolVersion); + expect(getExpansionStateVersion(currentUsers)).toBe(previousUserVersion); + const toolCardId = expectDefined(currentTools.keys().next().value, "retained tool card"); + expectDefined( + retainedPane.querySelector( + ".chat-group.user .chat-message-disclosure__toggle", + ), + "mounted user disclosure", + ).click(); + expectDefined( + retainedPane.querySelector(".chat-tool-msg-summary"), + "mounted tool disclosure", + ).click(); + + expect(currentTools.get(toolCardId)).toBe(true); + expect(staleTools.get(toolCardId)).toBe(false); + expect(currentUsers.size).toBe(1); + expect(staleUsers.size).toBe(0); + + const toolVisibilitySession = "tool-visibility-session"; + const toolVisibilityProps = { + ...props, + paneId: "tool-visibility-pane", + sessionKey: toolVisibilitySession, + messages: [ + { role: "user", content: "tool visibility prompt", timestamp: 1 }, + { + role: "toolResult", + toolCallId: "expanded-tool", + toolName: "browser.open", + content: "Expanded tool result", + timestamp: 2, + }, + { role: "assistant", content: "The first tool completed.", timestamp: 3 }, + { role: "user", content: "Show the next tool result.", timestamp: 4 }, + { + role: "toolResult", + toolCallId: "collapsed-tool", + toolName: "browser.open", + content: "Collapsed tool result", + timestamp: 5, + }, + ], + }; + const toolVisibilityController = createTestTranscript(); + const toolVisibilityPane = document.body.appendChild(document.createElement("div")); + const renderToolVisibility = (next = toolVisibilityProps) => + render(renderChatThread(next, toolVisibilityController), toolVisibilityPane); + renderToolVisibility(); + const visibilityState = getExpandedToolCards(toolVisibilitySession); + const visibilityIds = [...visibilityState.keys()].filter((key) => key.startsWith("toolmsg:")); + const expandedToolId = expectDefined(visibilityIds[0], "expanded standalone tool disclosure"); + const collapsedToolId = expectDefined(visibilityIds[1], "collapsed standalone tool disclosure"); + const disclosureButtons = () => + Array.from( + toolVisibilityPane.querySelectorAll(".chat-tool-msg-summary"), + ).filter((button) => !button.closest(".chat-tool-msg-body")); + expect(disclosureButtons()).toHaveLength(2); + expect(disclosureButtons().map((button) => button.getAttribute("aria-expanded"))).toEqual([ + "false", + "false", + ]); + expectDefined(disclosureButtons()[0], "first mounted tool disclosure").click(); + renderToolVisibility(); + expectDefined(disclosureButtons()[1], "second mounted tool disclosure").click(); + renderToolVisibility(); + expectDefined(disclosureButtons()[1], "second mounted tool disclosure").click(); + renderToolVisibility(); + expect(disclosureButtons().map((button) => button.getAttribute("aria-expanded"))).toEqual([ + "true", + "false", + ]); + + renderToolVisibility({ ...toolVisibilityProps, showToolCalls: false }); + expect(disclosureButtons()).toHaveLength(0); + renderToolVisibility(); + + expect(disclosureButtons()).toHaveLength(2); + expect(disclosureButtons().map((button) => button.getAttribute("aria-expanded"))).toEqual([ + "true", + "false", + ]); + expect(visibilityState.get(expandedToolId)).toBe(true); + expect(visibilityState.get(collapsedToolId)).toBe(false); + renderToolVisibility({ + ...toolVisibilityProps, + messages: toolVisibilityProps.messages.filter( + (message) => !("toolCallId" in message && message.toolCallId === "expanded-tool"), + ), + }); + expect(visibilityState.has(expandedToolId)).toBe(false); + expect(visibilityState.get(collapsedToolId)).toBe(false); + }); +}); diff --git a/ui/src/pages/chat/components/chat-transcript-projection.ts b/ui/src/pages/chat/components/chat-transcript-projection.ts new file mode 100644 index 000000000000..c02172584151 --- /dev/null +++ b/ui/src/pages/chat/components/chat-transcript-projection.ts @@ -0,0 +1,681 @@ +// Chat-item projection, expansion, reply hydration, and guarded row rendering. +import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice"; +import { html, nothing, type TemplateResult } from "lit"; +import { guard } from "lit/directives/guard.js"; +import { classifySessionKind } from "../../../../../src/sessions/classify-session-kind.js"; +import { i18n } from "../../../i18n/index.ts"; +import type { MessageGroup } from "../../../lib/chat/chat-types.ts"; +import { extractTextCached } from "../../../lib/chat/message-extract.ts"; +import { normalizeMessage } from "../../../lib/chat/message-normalizer.ts"; +import { + areUiSessionKeysEquivalent, + isUiGlobalScopeConfigured, + parseAgentSessionKey, + resolveUiGlobalAliasAgentId, +} from "../../../lib/sessions/session-key.ts"; +import { resolveTurnRecap, type TurnRecap } from "../chat-progress.ts"; +import { + assistantGroupCanOwnActiveRunStatus, + assistantMessageExpansionSignature, + buildCachedChatItems, + coalesceActivityRuns, + coalesceStreamRuns, + collapseCompletedTurnWork, + getExpansionStateVersion, + getExpandedAssistantMessages, + getExpandedToolCards, + getExpandedUserMessages, + persistedMessageEntryId, + setExpansionState, + syncToolCardExpansionState, +} from "../chat-thread.ts"; +import { getToolTitlesVersion } from "../tool-titles.ts"; +import { renderBackgroundTasksStatusRow } from "./chat-background-tasks-status.ts"; +import { renderChatDivider, renderChatNotice } from "./chat-divider.ts"; +import { resolveMessageGroupSenderLabel } from "./chat-message-group.ts"; +import { resolveMessageReplyText } from "./chat-message-markdown.ts"; +import { + getChatMediaRenderVersion, + renderActivityGroup, + renderMessageGroup, + renderStreamGroup, + renderWorkGroupSummary, + type MessageReplyTarget, + type StreamGroupOptions, + type StreamGroupPart, +} from "./chat-message.ts"; +import { renderRealtimeTalkConversation } from "./chat-realtime-controls.ts"; +import { + closeTranscriptSearch, + getTranscriptState, + type ChatThreadProps, + type ChatThreadState, +} from "./chat-thread-interactions.ts"; +import type { + ChatTranscriptSession, + TranscriptAnnouncement, + TranscriptRow, +} from "./chat-transcript-controller.ts"; +import { resolveAssistantDisplayAvatar } from "./chat-welcome.ts"; +import { renderTurnRecapRow } from "./chat-working-indicator.ts"; + +type ChatTranscriptProjection = { + isDirectThread: boolean; + isEmpty: boolean; + showLoadingSkeleton: boolean; + searchOpen: boolean; + renderRows: (overlay?: unknown) => TemplateResult; +}; + +type ChatRenderItem = ReturnType[number]; +const CHAT_TRANSCRIPT_ANNOUNCEMENT_MAX_CHARS = 500; + +type LoadedReplySource = { + rowKey: string; + preview: MessageReplyTarget & { sourceMessageId: string }; +}; + +function projectResolvedReplyPreview( + message: unknown, + replyToId: string, + props: Pick, +): LoadedReplySource["preview"] | undefined { + const normalized = normalizeMessage(message); + const text = resolveMessageReplyText(message); + if (!text) { + return undefined; + } + const group: MessageGroup = { + kind: "group", + key: replyToId, + role: normalized.role, + senderLabel: normalized.senderLabel, + ...(normalized.sender ? { sender: normalized.sender } : {}), + messages: [{ key: replyToId, message }], + timestamp: normalized.timestamp, + isStreaming: false, + }; + const sourceMessageId = persistedMessageEntryId(message) ?? replyToId; + return { + messageId: sourceMessageId, + sourceMessageId, + senderLabel: resolveMessageGroupSenderLabel(group, props), + text, + }; +} + +function latestTranscriptAnnouncement( + items: readonly ChatRenderItem[], +): TranscriptAnnouncement | null { + for (let itemIndex = items.length - 1; itemIndex >= 0; itemIndex -= 1) { + const item = items[itemIndex]; + if (!item || item.kind !== "group" || item.role.toLowerCase() !== "assistant") { + continue; + } + for (let messageIndex = item.messages.length - 1; messageIndex >= 0; messageIndex -= 1) { + const message = item.messages[messageIndex]?.message; + const text = extractTextCached(message)?.trim(); + if (text) { + return { + key: item.key, + text: truncateUtf16Safe(text, CHAT_TRANSCRIPT_ANNOUNCEMENT_MAX_CHARS), + }; + } + } + } + return null; +} + +function chatRenderItemGuardDependencies(item: ChatRenderItem): readonly unknown[] { + if (item.kind === "stream-run") { + return [item.key, ...item.parts]; + } + if (item.kind === "work-group") { + return [item.key, item.durationMs, item.hasError, ...item.groups]; + } + if (item.kind === "activity-run") { + return [item.key, ...item.groups]; + } + return [item]; +} + +function trackTranscriptRenderDependencies( + state: ChatThreadState, + dependencies: unknown[], +): unknown[] { + const previous = state.transcriptRenderDependencies; + const nextLength = dependencies.length - 1; + let changed = previous.length !== nextLength; + for (let index = 0; !changed && index < nextLength; index += 1) { + changed = !Object.is(previous[index], dependencies[index + 1]); + } + if (changed) { + // The first dependency is chatItems. Keep the shared context stable when + // only the live row changes, but invalidate every row for presentation changes. + state.transcriptRenderDependencies = dependencies.slice(1); + state.transcriptRenderContext = {}; + } + return dependencies; +} + +function guardChatRenderItems( + state: ChatThreadState, + // Live run status is not derivable from a row's own item identity: ownership + // is decided by sibling rows, and the usage counter ticks on run patches that + // touch nothing else. Rows showing status must re-render on both, or the + // memoized copy stacks a second claw row or freezes the token count. + liveStatus: (item: ChatRenderItem) => string, + render: (item: ChatRenderItem) => unknown, +) { + return (item: ChatRenderItem) => + guard( + [...chatRenderItemGuardDependencies(item), state.transcriptRenderContext, liveStatus(item)], + () => render(item), + ); +} + +export function projectChatTranscript( + props: ChatThreadProps, + transcript: ChatTranscriptSession, +): ChatTranscriptProjection { + const state = getTranscriptState(props.paneId); + const requestUpdate = props.onRequestUpdate ?? (() => {}); + const displayStream = props.stream ?? null; + const sessionHost = props.sessionHost ?? null; + // Equivalence, not exact match: the default session travels under alias + // keys ("main" vs "agent:main:main") depending on the caller. + const activeSession = props.sessions?.sessions?.find((row) => + areUiSessionKeysEquivalent(row.key, props.sessionKey), + ); + // Global-alias detection needs no session row: under configured global + // scope, agent::global and configured-main aliases route to the global + // stream even when the capped sessions list omits the canonical row (or it + // does not exist yet). The scope gate keeps per-sender main threads direct. + const isGlobalAliasKey = + parseAgentSessionKey(props.sessionKey)?.rest === "global" || + (sessionHost !== null && + isUiGlobalScopeConfigured(sessionHost) && + resolveUiGlobalAliasAgentId(sessionHost, props.sessionKey) !== null); + const reasoningLevel = activeSession?.reasoningLevel ?? "off"; + const showReasoning = props.showThinking && reasoningLevel !== "off"; + const assistantIdentity = { + name: props.assistantName, + avatar: resolveAssistantDisplayAvatar(props), + }; + const locale = i18n.getLocale(); + const searchFiltering = state.searchOpen && Boolean(state.searchQuery.trim()); + const chatItems = buildCachedChatItems({ + paneId: props.paneId, + sessionKey: props.sessionKey, + runId: props.runId === undefined ? (activeSession?.activeRunIds?.[0] ?? null) : props.runId, + locale, + messages: props.messages, + toolMessages: props.toolMessages, + streamSegments: props.streamSegments, + stream: displayStream, + streamStartedAt: props.streamStartedAt, + queue: props.queue, + showToolCalls: props.showToolCalls, + persistCommentary: props.persistCommentary, + runWorking: Boolean(props.runWorking), + runActive: Boolean(props.runActive), + planStatus: props.planStatus, + questionPrompts: props.questionPrompts, + loading: props.loading, + searchOpen: state.searchOpen, + searchQuery: state.searchQuery, + }); + syncToolCardExpansionState( + props.sessionKey, + chatItems, + Boolean(props.autoExpandToolCalls), + searchFiltering || !props.showToolCalls, + ); + const expandedToolCards = getExpandedToolCards(props.sessionKey); + const expandedUserMessages = getExpandedUserMessages(props.sessionKey); + const expandedAssistantMessages = getExpandedAssistantMessages(props.sessionKey); + const questionPrompts = new Map( + (props.questionPrompts ?? []).map((prompt) => [prompt.id, prompt]), + ); + const toggleToolCardExpanded = (toolCardId: string) => { + setExpansionState(expandedToolCards, toolCardId, !expandedToolCards.get(toolCardId)); + requestUpdate(); + }; + const toggleAssistantMessageExpanded = (messageId: string) => { + const current = expandedAssistantMessages.get(messageId); + if (current?.status === "loaded") { + expandedAssistantMessages.set(messageId, { + ...current, + expanded: !current.expanded, + revision: current.revision + 1, + }); + requestUpdate(); + return; + } + const loader = props.loadFullAssistantMessage; + if (!loader || current?.status === "loading") { + return; + } + const revision = (current?.revision ?? 0) + 1; + expandedAssistantMessages.set(messageId, { status: "loading", revision }); + requestUpdate(); + void loader({ + sessionKey: props.sessionKey, + ...(props.fullMessageAgentId ? { agentId: props.fullMessageAgentId } : {}), + messageId, + kind: "assistant_message", + }).then( + (result) => { + const pending = expandedAssistantMessages.get(messageId); + if (pending?.status !== "loading" || pending.revision !== revision) { + return; + } + const markdown = + result?.ok && result.message && typeof result.message === "object" + ? extractTextCached(result.message) + : null; + expandedAssistantMessages.set( + messageId, + markdown === null + ? { status: "error", revision: revision + 1 } + : { status: "loaded", expanded: true, markdown, revision: revision + 1 }, + ); + requestUpdate(); + }, + () => { + const pending = expandedAssistantMessages.get(messageId); + if (pending?.status !== "loading" || pending.revision !== revision) { + return; + } + expandedAssistantMessages.set(messageId, { status: "error", revision: revision + 1 }); + requestUpdate(); + }, + ); + }; + const hasRealtimeTalkConversation = (props.realtimeTalkConversation?.length ?? 0) > 0; + const isEmpty = chatItems.length === 0 && !props.loading && !hasRealtimeTalkConversation; + transcript.setContentReady(!props.loading); + // 1:1 sessions drop the avatar gutter entirely; group threads keep avatars + // as the always-visible identity marker. The canonical session kind decides; + // the sessions list is capped, so absent/unknown rows classify by key: + // global aliases first, then the same core key-shape helper the gateway + // uses. Message senderLabels are not a signal here: gateway sanitization + // labels 1:1 channel DM rows too. + const rowKind = activeSession?.kind; + const sessionKind = + rowKind && rowKind !== "unknown" + ? rowKind + : isGlobalAliasKey + ? "global" + : classifySessionKind(props.sessionKey); + // Only agent-solo kinds qualify: "global" aggregates every inbound context + // under session.scope="global" (including group/channel senders), so it + // keeps avatars like "group" and "unknown" do. An identity-resolving gateway + // (multi-user trusted proxy) also keeps them: several people share these + // sessions, so the author marker is signal, not decoration. + const isDirectThread = + (sessionKind === "direct" || sessionKind === "cron" || sessionKind === "spawn-child") && + !props.userId; + const showLoadingSkeleton = props.loading && chatItems.length === 0; + const threadContextWindow = + activeSession?.contextTokens ?? props.sessions?.defaults?.contextTokens ?? null; + const activeContinuationByGroupKey = new Map< + string, + { parts: StreamGroupPart[]; options: StreamGroupOptions } + >(); + const turnRecapByGroupKey = new Map(); + const loadedReplySources = new Map(); + const resolvedReplyPreviews = new Map(); + const resolveReplyPreview = (replyToId: string) => { + const loaded = loadedReplySources.get(replyToId)?.preview; + if (loaded) { + return loaded; + } + if (resolvedReplyPreviews.has(replyToId)) { + return resolvedReplyPreviews.get(replyToId); + } + const message = props.replyMessageAccess?.read(replyToId); + const preview = message ? projectResolvedReplyPreview(message, replyToId, props) : undefined; + resolvedReplyPreviews.set(replyToId, preview); + return preview; + }; + const sharedMessageRenderOptions = { + onOpenSidebar: props.onOpenSidebar, + sessionKey: props.sessionKey, + boardProvider: props.boardProvider, + agentId: props.fullMessageAgentId, + runActive: props.runActive, + onOpenWorkspaceFile: props.onOpenWorkspaceFile, + onRequestUpdate: requestUpdate, + basePath: props.basePath, + localMediaPreviewRoots: props.localMediaPreviewRoots ?? [], + assistantAttachmentAuthToken: props.assistantAttachmentAuthToken ?? null, + resolveArtifactDownload: props.resolveArtifactDownload, + onAssistantAttachmentLoaded: props.onAssistantAttachmentLoaded, + onRequestOpenImage: props.onRequestOpenImage, + onOpenImage: props.onOpenImage, + canvasPluginSurfaceUrl: props.canvasPluginSurfaceUrl, + embedSandboxMode: props.embedSandboxMode ?? "scripts", + allowExternalEmbedUrls: props.allowExternalEmbedUrls ?? false, + showAssistantAvatar: false, + } satisfies StreamGroupOptions; + const streamGroupOptions = { + ...sharedMessageRenderOptions, + assistant: assistantIdentity, + } satisfies StreamGroupOptions; + const renderGroupOptions = (item: MessageGroup) => { + const lastMessage = item.messages.at(-1)?.message; + const rewindEntryId = + item.role.toLowerCase() === "user" && lastMessage + ? persistedMessageEntryId(lastMessage) + : null; + return { + ...sharedMessageRenderOptions, + showReasoning, + showToolCalls: props.showToolCalls, + autoExpandToolCalls: Boolean(props.autoExpandToolCalls), + isToolMessageExpanded: (messageId: string) => expandedToolCards.get(messageId), + onToggleToolMessageExpanded: (messageId: string, expanded?: boolean) => { + setExpansionState( + expandedToolCards, + messageId, + !(expanded ?? expandedToolCards.get(messageId) ?? false), + ); + requestUpdate(); + }, + isUserMessageExpanded: (messageId: string) => expandedUserMessages.get(messageId) ?? false, + onToggleUserMessageExpanded: (messageId: string) => { + setExpansionState(expandedUserMessages, messageId, !expandedUserMessages.get(messageId)); + requestUpdate(); + }, + loadFullAssistantMessage: props.loadFullAssistantMessage ?? undefined, + getAssistantMessageExpansion: (messageId: string) => expandedAssistantMessages.get(messageId), + onToggleAssistantMessageExpanded: toggleAssistantMessageExpanded, + isToolExpanded: (toolCardId: string) => expandedToolCards.get(toolCardId) ?? false, + onToggleToolExpanded: toggleToolCardExpanded, + assistantName: props.assistantName, + assistantAvatar: assistantIdentity.avatar, + userId: props.userId ?? null, + userName: props.userName ?? null, + userAvatar: props.userAvatar ?? null, + showAvatarGutter: !isDirectThread, + contextWindow: threadContextWindow, + onReply: props.onSetReply + ? (target) => state.transcriptRenderContext.onSetReply?.(target) + : undefined, + resolveReplyPreview, + onResolveReply: props.replyMessageAccess?.request, + onOpenReply: (replyToId: string) => state.transcriptRenderContext.onOpenReply?.(replyToId), + replyNavigationId: props.replyMessageAccess?.navigationId, + onRewind: + rewindEntryId && props.onRewindMessage + ? () => { + void Promise.resolve(props.onRewindMessage?.(rewindEntryId)).then((rewound) => { + if (rewound) { + props.onFocusComposer?.(); + } + }); + } + : undefined, + rewindDisabled: Boolean(props.runActive || props.runWorking), + activeContinuation: activeContinuationByGroupKey.get(item.key), + turnRecap: turnRecapByGroupKey.get(item.key), + } satisfies Parameters[1]; + }; + const renderGroupItem = (item: MessageGroup) => { + return renderMessageGroup(item, renderGroupOptions(item)); + }; + // Only the working indicator shows live usage, so rows without one keep + // memoizing across usage patches. + const workingUsageKey = `usage:${props.runOutputTokens ?? ""}`; + const liveStatusSignature = (item: ChatRenderItem): string => { + if (item.kind === "stream-run") { + return item.parts.some((part) => part.kind === "reading-indicator") ? workingUsageKey : ""; + } + if (item.kind !== "group") { + return ""; + } + const continuation = activeContinuationByGroupKey.get(item.key); + const recap = turnRecapByGroupKey.get(item.key); + // Part keys stand in for the rest of the continuation: its remaining + // options mirror props that already invalidate every row through the + // shared render context. + const continuationKey = continuation + ? `${continuation.parts.map((part) => part.key).join(" ")}${workingUsageKey}` + : ""; + const recapKey = recap ? `${recap.runtimeMs}:${recap.outputTokens ?? ""}` : ""; + return `${continuationKey}|${recapKey}`; + }; + const renderItem = guardChatRenderItems(state, liveStatusSignature, (item) => { + if (item.kind === "divider") { + return renderChatDivider(item, props.onOpenSessionCheckpoints); + } + if (item.kind === "notice") { + return renderChatNotice(item); + } + if (item.kind === "stream-run") { + return renderStreamGroup(item.parts, { + ...streamGroupOptions, + questionPrompts, + planStatus: props.planStatus, + planActive: Boolean(props.runActive), + startupPhase: props.startupStatus?.phase, + waitingApproval: props.waitingApproval, + runOutputTokens: props.runOutputTokens, + }); + } + if (item.kind === "work-group") { + const workExpanded = expandedToolCards.get(item.key) ?? item.hasError; + return html` + ${renderWorkGroupSummary(item, { + expanded: workExpanded, + onToggle: () => { + setExpansionState(expandedToolCards, item.key, !workExpanded); + requestUpdate(); + }, + })} + ${workExpanded ? item.groups.map((group) => renderGroupItem(group)) : nothing} + `; + } + if (item.kind === "activity-run") { + const firstGroup = item.groups[0]; + if (!firstGroup) { + return nothing; + } + if (item.groups.length === 1) { + return renderGroupItem(firstGroup); + } + return renderActivityGroup(item.groups, renderGroupOptions(firstGroup)); + } + if (item.kind === "group") { + return renderGroupItem(item); + } + if (item.kind === "question") { + return renderStreamGroup([item], { + questionPrompts, + }); + } + return nothing; + }); + const collapsedItems = coalesceActivityRuns( + collapseCompletedTurnWork(coalesceStreamRuns(chatItems), { + sessionKey: props.sessionKey, + runWorking: Boolean(props.runWorking), + searchActive: searchFiltering, + }), + { searchActive: searchFiltering }, + ); + // Watch/settle on actual indicator visibility (not runWorking): queued + // sends show the claw before the run starts, and the recap must never + // stack under a visible working row. + const workingIndicatorVisible = chatItems.some((item) => item.kind === "reading-indicator"); + const turnRecap = resolveTurnRecap(props.sessionKey, workingIndicatorVisible, activeSession); + const transcriptItems = collapsedItems.filter((item, index) => { + if (item.kind !== "stream-run") { + return true; + } + const previous = collapsedItems[index - 1]; + const isActiveStatusRun = + item.parts.some((part) => part.kind === "reading-indicator") && + item.parts.every((part) => part.kind === "reading-indicator" || part.kind === "plan"); + if ( + previous?.kind !== "group" || + !isActiveStatusRun || + !assistantGroupCanOwnActiveRunStatus(previous) + ) { + return true; + } + // A reply and its still-running state are one turn-level presentation. + // Keeping the status in the reply avoids a second claw/assistant row. + activeContinuationByGroupKey.set(previous.key, { + parts: item.parts, + options: { + ...streamGroupOptions, + planStatus: props.planStatus, + planActive: Boolean(props.runActive), + startupPhase: props.startupStatus?.phase, + waitingApproval: props.waitingApproval, + runOutputTokens: props.runOutputTokens, + }, + }); + return false; + }); + for (const item of transcriptItems) { + if (item.kind !== "group") { + continue; + } + const senderLabel = resolveMessageGroupSenderLabel(item, { + assistantName: props.assistantName, + userId: props.userId, + userName: props.userName, + userAvatar: props.userAvatar, + }); + for (const source of item.messages) { + const sourceMessageId = persistedMessageEntryId(source.message); + const text = resolveMessageReplyText(source.message); + if (sourceMessageId && text) { + loadedReplySources.set(sourceMessageId, { + rowKey: item.key, + preview: { + messageId: source.key, + sourceMessageId, + senderLabel, + text, + }, + }); + } + } + } + transcript.syncMessageRows( + new Map([...loadedReplySources].map(([messageId, source]) => [messageId, source.rowKey])), + ); + let turnRecapOwnerKey: string | null = null; + if (turnRecap !== null) { + const lastItem = transcriptItems.at(-1); + if (lastItem?.kind === "group" && assistantGroupCanOwnActiveRunStatus(lastItem)) { + turnRecapByGroupKey.set(lastItem.key, turnRecap); + turnRecapOwnerKey = lastItem.key; + } + } + const transcriptRows: TranscriptRow[] = transcriptItems.map((item) => ({ + kind: "item", + key: item.key, + item, + })); + const realtimeConversation = renderRealtimeTalkConversation(props); + if (realtimeConversation !== nothing) { + transcriptRows.push({ + kind: "content", + key: "realtime-talk", + content: realtimeConversation, + }); + } + if (turnRecap !== null && turnRecapOwnerKey === null && !isEmpty && !showLoadingSkeleton) { + transcriptRows.push({ + kind: "content", + key: "turn-recap", + content: renderTurnRecapRow(turnRecap), + }); + } + const backgroundTasks = + !props.runWorking && !isEmpty && !showLoadingSkeleton + ? renderBackgroundTasksStatusRow(props.backgroundTasks) + : nothing; + if (backgroundTasks !== nothing) { + transcriptRows.push({ + kind: "content", + key: "background-tasks", + content: backgroundTasks, + }); + } + trackTranscriptRenderDependencies(state, [ + chatItems, + locale, + expandedToolCards, + getExpansionStateVersion(expandedToolCards), + expandedUserMessages, + getExpansionStateVersion(expandedUserMessages), + assistantMessageExpansionSignature(expandedAssistantMessages), + getChatMediaRenderVersion(), + // The host minute poll requests an update; this key crosses row guard() memoization. + Math.floor(Date.now() / 60_000), + getToolTitlesVersion(), + props.sessionKey, + props.boardProvider, + props.boardProvider?.canPinWidgets, + props.boardProvider?.canPinMcpApps, + props.boardProvider?.snapshot$.value.revision, + props.fullMessageAgentId, + Boolean(props.loadFullAssistantMessage), + showReasoning, + props.showToolCalls, + Boolean(props.runActive), + Boolean(props.runWorking), + props.startupStatus?.phase, + Boolean(props.waitingApproval), + props.planStatus, + props.questionPrompts, + Boolean(props.autoExpandToolCalls), + props.assistantName, + assistantIdentity.avatar, + props.userId, + props.userName, + props.userAvatar, + props.basePath, + (props.localMediaPreviewRoots ?? []).join("\u0000"), + props.assistantAttachmentAuthToken, + props.canvasPluginSurfaceUrl, + props.embedSandboxMode ?? "scripts", + props.allowExternalEmbedUrls ?? false, + threadContextWindow, + Boolean(props.onSetReply), + props.replyMessageAccess?.revision ?? 0, + props.replyMessageAccess?.navigationId ?? "", + turnRecap === null ? "" : `${turnRecap.runtimeMs}:${turnRecap.outputTokens ?? ""}`, + ]); + state.transcriptRenderContext.onSetReply = props.onSetReply; + state.transcriptRenderContext.onOpenReply = (replyToId) => { + if (loadedReplySources.has(replyToId)) { + transcript.revealMessage(replyToId); + return; + } + if (searchFiltering) { + closeTranscriptSearch(state, requestUpdate); + } + props.replyMessageAccess?.open(replyToId); + }; + return { + isDirectThread, + isEmpty, + showLoadingSkeleton, + searchOpen: state.searchOpen, + renderRows: (overlay: unknown = nothing) => + transcript.render( + transcriptRows, + (row) => (row.kind === "item" ? renderItem(row.item) : row.content), + latestTranscriptAnnouncement(collapsedItems), + props.announceTranscript !== false && !state.searchOpen && !props.loading, + overlay, + ), + }; +} diff --git a/ui/src/pages/chat/components/chat-transcript-render.test.ts b/ui/src/pages/chat/components/chat-transcript-render.test.ts new file mode 100644 index 000000000000..edf638f297af --- /dev/null +++ b/ui/src/pages/chat/components/chat-transcript-render.test.ts @@ -0,0 +1,271 @@ +/* @vitest-environment jsdom */ + +import { render } from "lit"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createTestTranscript } from "../chat-view.test-helpers.ts"; +import { renderTranscriptSearch, toggleTranscriptSearch } from "./chat-thread-interactions.ts"; +import { renderChatThread } from "./chat-thread.ts"; +import { + flushDeferredRowPrune, + installTranscriptDomMocks, + resetTranscriptTestDom, + threadProps, +} from "./chat-transcript.test-support.ts"; + +describe("chat transcript rendering", () => { + beforeEach(installTranscriptDomMocks); + afterEach(resetTranscriptTestDom); + + it("resolves persisted replies to their source and highlights it on click", async () => { + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const props = threadProps("pane-reply-preview", "agent:main:main", [ + { + role: "assistant", + content: "The original answer", + __openclaw: { id: "source-message" }, + timestamp: 1_000, + }, + { + role: "user", + content: "Follow up", + __openclaw: { id: "reply-message", replyToId: "source-message" }, + timestamp: 2_000, + }, + ]); + render(renderChatThread(props, transcript), container); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const preview = container.querySelector(".chat-reply-preview--message"); + expect(preview?.textContent).toContain("Replying to Molty"); + expect(preview?.textContent).toContain("The original answer"); + expect(preview?.textContent).not.toContain("source-message"); + + preview?.click(); + await Promise.resolve(); + + const sourceBubble = [...container.querySelectorAll(".chat-bubble")].find( + (bubble) => bubble.dataset.entryId === "source-message", + ); + expect(sourceBubble?.classList.contains("chat-bubble--reply-target")).toBe(true); + transcript.hostDisconnected(); + }); + + it("hydrates an unloaded reply preview without inserting its source row", async () => { + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + let resolvedMessage: unknown = undefined; + const request = vi.fn(); + const open = vi.fn(); + const props = { + ...threadProps("pane-reply-hydration", "agent:main:main", [ + { + role: "user", + content: "Follow up", + __openclaw: { id: "reply-message", replyToId: "source-message" }, + timestamp: 2_000, + }, + ]), + replyMessageAccess: { + revision: 0, + navigationId: null, + read: () => resolvedMessage, + request, + open, + }, + }; + const rerender = () => { + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + }; + rerender(); + transcript.hostConnected(); + await flushDeferredRowPrune(); + + expect(request).toHaveBeenCalledWith("source-message"); + expect(container.querySelector("[data-entry-id='source-message']")).toBeNull(); + + resolvedMessage = { + role: "assistant", + content: "The original answer", + __openclaw: { id: "source-message" }, + timestamp: 1_000, + }; + props.replyMessageAccess.revision += 1; + rerender(); + + const preview = container.querySelector(".chat-reply-preview--message"); + expect(preview?.textContent).toContain("Replying to Molty"); + expect(preview?.textContent).toContain("The original answer"); + preview?.click(); + expect(open).toHaveBeenCalledWith("source-message"); + transcript.hostDisconnected(); + }); + + it("clears search before navigating to a filtered reply target", async () => { + const transcript = createTestTranscript(); + const searchContainer = document.body.appendChild(document.createElement("div")); + const threadContainer = document.body.appendChild(document.createElement("div")); + const open = vi.fn(); + const paneId = "pane-filtered-reply-navigation"; + const props = { + ...threadProps(paneId, "agent:main:main", [ + { + role: "assistant", + content: "The original answer", + __openclaw: { id: "source-message" }, + timestamp: 1_000, + }, + { + role: "user", + content: "Follow up", + __openclaw: { + id: "reply-message", + replyToId: "source-message", + replyToPreview: { text: "The original answer", senderLabel: "Molty" }, + }, + timestamp: 2_000, + }, + ]), + replyMessageAccess: { + revision: 0, + navigationId: null, + read: () => undefined, + request: vi.fn(), + open, + }, + }; + const rerender = () => { + render(renderTranscriptSearch(paneId, rerender), searchContainer); + render( + renderChatThread({ ...props, onRequestUpdate: rerender }, transcript), + threadContainer, + ); + transcript.hostUpdated(); + }; + toggleTranscriptSearch(paneId, rerender); + rerender(); + transcript.hostConnected(); + const input = searchContainer.querySelector("input"); + expect(input).not.toBeNull(); + input!.value = "Follow up"; + input!.dispatchEvent(new Event("input", { bubbles: true })); + await flushDeferredRowPrune(); + + expect(threadContainer.querySelector("[data-entry-id='source-message']")).toBeNull(); + const preview = threadContainer.querySelector( + ".chat-reply-preview--message", + ); + expect(preview).not.toBeNull(); + preview!.click(); + + expect(open).toHaveBeenCalledWith("source-message"); + expect(searchContainer.querySelector("input")).toBeNull(); + transcript.hostDisconnected(); + }); + + it("loads a truncated assistant message once and keeps the full text visible", async () => { + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const loadFullAssistantMessage = vi.fn().mockResolvedValue({ + ok: true, + message: { role: "assistant", content: "Complete assistant content." }, + }); + function rerender() { + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + } + const props = { + ...threadProps("pane-assistant-expand", "agent:work:main", [ + { + role: "assistant", + content: "Preview\n...(truncated)...", + __openclaw: { id: "assistant-full-1" }, + timestamp: 1_000, + }, + ]), + fullMessageAgentId: "work", + loadFullAssistantMessage, + onRequestUpdate: rerender, + }; + rerender(); + transcript.hostConnected(); + transcript.hostUpdated(); + + await vi.waitFor(() => expect(container.textContent).toContain("Complete assistant content.")); + expect(loadFullAssistantMessage).toHaveBeenCalledOnce(); + expect(loadFullAssistantMessage).toHaveBeenCalledWith({ + sessionKey: "agent:work:main", + agentId: "work", + messageId: "assistant-full-1", + kind: "assistant_message", + }); + + expect(container.querySelector(".chat-message-disclosure__toggle")).toBeNull(); + expect(container.textContent).toContain("Complete assistant content."); + expect(loadFullAssistantMessage).toHaveBeenCalledOnce(); + transcript.hostDisconnected(); + }); + + it("keeps transport-cut assistant text as received when full content is unavailable", async () => { + const transcript = createTestTranscript(); + const container = document.body.appendChild(document.createElement("div")); + const loadFullAssistantMessage = vi.fn().mockRejectedValue(new Error("offline")); + function rerender() { + render(renderChatThread(props, transcript), container); + transcript.hostUpdated(); + } + const props = { + ...threadProps("pane-assistant-retry", "agent:main:main", [ + { + role: "assistant", + content: "Preview\n...(truncated)...", + __openclaw: { id: "assistant-retry-1" }, + timestamp: 1_000, + }, + ]), + loadFullAssistantMessage, + onRequestUpdate: rerender, + }; + rerender(); + transcript.hostConnected(); + transcript.hostUpdated(); + + await vi.waitFor(() => expect(loadFullAssistantMessage).toHaveBeenCalledOnce()); + expect(container.textContent).toContain("Preview"); + expect(container.textContent).toContain("...(truncated)..."); + expect(container.querySelector(".chat-message-disclosure__toggle")).toBeNull(); + transcript.hostDisconnected(); + }); + + it.each(["Enter", " "])("opens focused transcript file links with %j", async (key) => { + const transcript = createTestTranscript(); + const onOpenWorkspaceFile = vi.fn(); + const onHistoryIntent = vi.fn(); + const container = document.body.appendChild(document.createElement("div")); + const props = { + ...threadProps("pane-file-link", "agent:main:main", [ + { role: "assistant", content: "Inspect `src/chat.ts:17`", timestamp: 1_000 }, + ]), + onOpenWorkspaceFile, + onHistoryIntent, + }; + render(renderChatThread(props, transcript), container); + transcript.hostConnected(); + transcript.hostUpdated(); + await flushDeferredRowPrune(); + + const link = container.querySelector("a.markdown-file-link"); + link?.focus(); + expect(document.activeElement).toBe(link); + const event = new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }); + link?.dispatchEvent(event); + + expect(event.defaultPrevented).toBe(true); + expect(onOpenWorkspaceFile).toHaveBeenCalledWith({ path: "src/chat.ts", line: 17 }); + expect(onHistoryIntent).not.toHaveBeenCalled(); + transcript.hostDisconnected(); + }); +}); diff --git a/ui/src/pages/chat/components/chat-transcript.test-support.ts b/ui/src/pages/chat/components/chat-transcript.test-support.ts new file mode 100644 index 000000000000..64b6e43e50ff --- /dev/null +++ b/ui/src/pages/chat/components/chat-transcript.test-support.ts @@ -0,0 +1,121 @@ +import { vi } from "vitest"; +import { resetChatThreadState } from "../chat-thread.ts"; +import { resetThreadPresentation } from "./chat-thread-interactions.ts"; + +export const observedElements = new Set(); +export const resizeObservers = new Set(); +export const transcriptDomState = { measuredRowHeight: 100 }; + +class RecordingResizeObserver implements ResizeObserver { + private readonly targets = new Set(); + + constructor(private readonly callback: ResizeObserverCallback) { + resizeObservers.add(this); + } + + observe(target: Element): void { + this.targets.add(target); + observedElements.add(target); + } + + unobserve(target: Element): void { + this.targets.delete(target); + observedElements.delete(target); + } + + disconnect(): void { + for (const target of this.targets) { + observedElements.delete(target); + } + this.targets.clear(); + resizeObservers.delete(this); + } + + emit(width: number, height: number): void { + const entries = [...this.targets].map( + (target) => + ({ + target, + borderBoxSize: [{ inlineSize: width, blockSize: height }], + }) as unknown as ResizeObserverEntry, + ); + if (entries.length > 0) { + this.callback(entries, this); + } + } + + observes(target: Element): boolean { + return this.targets.has(target); + } +} + +const defaultMessages = [ + { role: "user", content: "message one", timestamp: 1_000 }, + { role: "assistant", content: "reply one", timestamp: 2_000 }, + { role: "user", content: "message two", timestamp: 3_000 }, + { role: "assistant", content: "reply two", timestamp: 4_000 }, +]; + +export function threadProps( + paneId: string, + sessionKey = "agent:main:main", + messages: unknown[] = defaultMessages, +) { + return { + paneId, + sessionKey, + loading: false, + messages, + toolMessages: [], + streamSegments: [], + stream: null, + streamStartedAt: null, + queue: [], + showThinking: false, + showToolCalls: false, + sessions: null, + assistantName: "Molty", + assistantAvatar: null, + onDraftChange: () => {}, + onSend: () => {}, + }; +} + +export function transcriptRows(container: HTMLElement): HTMLElement[] { + return [...container.querySelectorAll(".chat-virtual-row")]; +} + +export async function flushDeferredRowPrune(): Promise { + await new Promise((resolve) => { + setTimeout(resolve, 0); + }); +} + +export function installTranscriptDomMocks(): void { + observedElements.clear(); + resizeObservers.clear(); + transcriptDomState.measuredRowHeight = 100; + vi.stubGlobal("ResizeObserver", RecordingResizeObserver); + vi.spyOn(HTMLElement.prototype, "offsetHeight", "get").mockImplementation( + () => transcriptDomState.measuredRowHeight, + ); + vi.spyOn(Element.prototype, "getBoundingClientRect").mockReturnValue({ + x: 0, + y: 0, + top: 0, + left: 0, + right: 800, + bottom: 600, + width: 800, + height: 600, + toJSON: () => ({}), + } as DOMRect); +} + +export function resetTranscriptTestDom(): void { + vi.restoreAllMocks(); + vi.unstubAllGlobals(); + resetThreadPresentation(); + resetChatThreadState(); + document.body.replaceChildren(); +} diff --git a/ui/src/pages/chat/persisted-set.ts b/ui/src/pages/chat/persisted-set.ts deleted file mode 100644 index f652ef37d1eb..000000000000 --- a/ui/src/pages/chat/persisted-set.ts +++ /dev/null @@ -1,46 +0,0 @@ -import { getSafeLocalStorage } from "../../local-storage.ts"; - -export class PersistedSet { - protected values = new Set(); - - constructor( - private readonly key: string, - isValue: (value: unknown) => value is T, - ) { - try { - const parsed: unknown = JSON.parse(getSafeLocalStorage()?.getItem(key) ?? ""); - if (Array.isArray(parsed)) { - this.values = new Set(parsed.filter(isValue)); - } - } catch { - // Storage is optional and corrupt entries are ignored. - } - } - - has(value: T): boolean { - return this.values.has(value); - } - - protected add(value: T): void { - this.values.add(value); - this.save(); - } - - protected remove(value: T): void { - this.values.delete(value); - this.save(); - } - - clear(): void { - this.values.clear(); - this.save(); - } - - private save(): void { - try { - getSafeLocalStorage()?.setItem(this.key, JSON.stringify([...this.values])); - } catch { - // Storage is optional. - } - } -} diff --git a/ui/src/pages/chat/pinned-messages.ts b/ui/src/pages/chat/pinned-messages.ts deleted file mode 100644 index e16c3a299504..000000000000 --- a/ui/src/pages/chat/pinned-messages.ts +++ /dev/null @@ -1,30 +0,0 @@ -// Control UI chat module implements pinned messages behavior. -import { PersistedSet } from "./persisted-set.ts"; - -const PREFIX = "openclaw:pinned:"; - -export class PinnedMessages extends PersistedSet { - constructor(sessionKey: string) { - super(PREFIX + sessionKey, (value): value is number => typeof value === "number"); - } - - get indices(): Set { - return this.values; - } - - pin(index: number): void { - this.add(index); - } - - unpin(index: number): void { - this.remove(index); - } - - toggle(index: number): void { - if (this.has(index)) { - this.unpin(index); - } else { - this.pin(index); - } - } -} From e30df720459b2f31fe035ab05f731ae371b133dc Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:50:56 -0700 Subject: [PATCH 016/165] fix(worker): keep source bundles npm-installable (#122430) --- packages/ai/package.json | 4 +- packages/ai/src/package-dependencies.test.ts | 5 +- pnpm-lock.yaml | 7 +- .../worker-environments/bundle.test.ts | 71 +++++++++++++++++++ 4 files changed, 81 insertions(+), 6 deletions(-) diff --git a/packages/ai/package.json b/packages/ai/package.json index b7748a8b048c..1af4b08ceaa3 100644 --- a/packages/ai/package.json +++ b/packages/ai/package.json @@ -101,11 +101,13 @@ "@anthropic-ai/sdk": "0.115.0", "@google/genai": "2.13.0", "@mistralai/mistralai": "2.5.0", - "@openclaw/normalization-core": "workspace:*", "openai": "6.49.0", "partial-json": "0.1.7", "typebox": "1.3.6" }, + "devDependencies": { + "@openclaw/normalization-core": "workspace:*" + }, "engines": { "node": ">=22.19.0" }, diff --git a/packages/ai/src/package-dependencies.test.ts b/packages/ai/src/package-dependencies.test.ts index 3fccc9c2206f..4fd2ab7aba6f 100644 --- a/packages/ai/src/package-dependencies.test.ts +++ b/packages/ai/src/package-dependencies.test.ts @@ -44,7 +44,7 @@ async function productionImportsPackage(packageName: string): Promise { } describe("@openclaw/ai source dependency contract", () => { - it("declares normalization-core while production source imports it", async () => { + it("declares bundled normalization-core imports as a workspace dev dependency", async () => { const manifest = JSON.parse( await fs.readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8"), ) as { @@ -53,6 +53,7 @@ describe("@openclaw/ai source dependency contract", () => { }; expect(await productionImportsPackage("@openclaw/normalization-core")).toBe(true); - expect(manifest.dependencies?.["@openclaw/normalization-core"]).toBe("workspace:*"); + expect(manifest.dependencies?.["@openclaw/normalization-core"]).toBeUndefined(); + expect(manifest.devDependencies?.["@openclaw/normalization-core"]).toBe("workspace:*"); }); }); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 04deda2564f5..79f8a00f8f09 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2167,9 +2167,6 @@ importers: '@mistralai/mistralai': specifier: 2.5.0 version: 2.5.0(@opentelemetry/api@1.9.1) - '@openclaw/normalization-core': - specifier: workspace:* - version: link:../normalization-core openai: specifier: 6.49.0 version: 6.49.0(@aws-sdk/credential-provider-node@3.972.72)(@smithy/hash-node@4.4.14)(@smithy/signature-v4@5.6.10)(ws@8.21.1)(zod@4.4.3) @@ -2179,6 +2176,10 @@ importers: typebox: specifier: 1.3.6 version: 1.3.6 + devDependencies: + '@openclaw/normalization-core': + specifier: workspace:* + version: link:../normalization-core packages/gateway-client: dependencies: diff --git a/src/gateway/worker-environments/bundle.test.ts b/src/gateway/worker-environments/bundle.test.ts index 34a48fe75ce5..edfad23d64b2 100644 --- a/src/gateway/worker-environments/bundle.test.ts +++ b/src/gateway/worker-environments/bundle.test.ts @@ -2,6 +2,7 @@ import fs from "node:fs/promises"; import path from "node:path"; import * as tar from "tar"; import { describe, expect, it, vi } from "vitest"; +import { runCommandWithTimeout } from "../../process/exec.js"; import { withTestDir } from "../../test-helpers/temp-dir.js"; import { createWorkerBundleProducer, @@ -246,6 +247,76 @@ describe("worker bundle producer", () => { }); }); + it("installs a source bundle when the AI workspace import is bundled", async () => { + await withTestDir({ prefix: "openclaw-worker-bundle-npm-install-" }, async (root) => { + const repoRoot = path.resolve(import.meta.dirname, "../../.."); + const aiManifest = JSON.parse( + await fs.readFile(path.join(repoRoot, "packages/ai/package.json"), "utf8"), + ) as { + dependencies?: Record; + devDependencies?: Record; + }; + const dependencyFields = (["dependencies", "devDependencies"] as const).filter( + (field) => aiManifest[field]?.["@openclaw/normalization-core"] !== undefined, + ); + if (dependencyFields.length !== 1) { + throw new Error( + "@openclaw/ai must classify normalization-core in exactly one dependency field", + ); + } + const dependencyField = dependencyFields[0]!; + const normalizationCoreSpec = aiManifest[dependencyField]?.["@openclaw/normalization-core"]; + if (!normalizationCoreSpec?.startsWith("workspace:")) { + throw new Error("@openclaw/ai must use a workspace normalization-core dependency"); + } + const packageRoot = path.join(root, "package"); + await writeFixture(packageRoot, [["dist/entry.js", 'import "@openclaw/ai";\nexport {};\n']]); + await fs.writeFile( + path.join(packageRoot, "package.json"), + `${JSON.stringify({ + name: "openclaw", + version: "1.2.3", + type: "module", + files: ["dist/"], + dependencies: { "@openclaw/ai": "workspace:*" }, + })}\n`, + "utf8", + ); + const vendorSource = path.join(packageRoot, "node_modules/@openclaw/ai"); + await fs.mkdir(path.join(vendorSource, "dist"), { recursive: true }); + await fs.writeFile( + path.join(vendorSource, "package.json"), + `${JSON.stringify({ + name: "@openclaw/ai", + version: "1.2.3", + type: "module", + main: "./dist/index.js", + [dependencyField]: { "@openclaw/normalization-core": normalizationCoreSpec }, + })}\n`, + "utf8", + ); + await fs.writeFile(path.join(vendorSource, "dist/index.js"), "export {};\n", "utf8"); + + const bundle = await createWorkerBundleProducer({ + packageRoot, + cacheDir: path.join(root, "cache"), + }).prepare(); + const extractRoot = path.join(root, "extract"); + await fs.mkdir(extractRoot); + await tar.extract({ file: bundle.tarballPath, cwd: extractRoot }); + + const install = await runCommandWithTimeout( + ["npm", "install", "--ignore-scripts", "--omit=dev", "--no-audit", "--no-fund"], + { + cwd: extractRoot, + env: { NPM_CONFIG_CACHE: path.join(root, "npm-cache") }, + timeoutMs: 30_000, + }, + ); + expect(install.code, install.stderr).toBe(0); + }); + }); + it("fails closed when a dist-referenced workspace package is not installed", async () => { await withTestDir({ prefix: "openclaw-worker-bundle-vendor-missing-" }, async (root) => { const packageRoot = path.join(root, "package"); From 141f943a411cfbf5d1a91968652570d484d2ff93 Mon Sep 17 00:00:00 2001 From: Ayaan Zaidi Date: Wed, 12 Aug 2026 10:25:47 +0530 Subject: [PATCH 017/165] fix(delivery): clear resolved ambiguity notices (#122438) Clear stale uncertainty debt when the same final reaches an authoritative terminal outcome, preventing false notices on the next inbound turn. Co-authored-by: Ayaan Zaidi --- src/infra/outbound/delivery-completion.test.ts | 2 +- src/infra/outbound/delivery-completion.ts | 13 ++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/infra/outbound/delivery-completion.test.ts b/src/infra/outbound/delivery-completion.test.ts index 0bbcbddbae49..fabeae0e79bf 100644 --- a/src/infra/outbound/delivery-completion.test.ts +++ b/src/infra/outbound/delivery-completion.test.ts @@ -136,7 +136,7 @@ describe("pending-final delivery completion", () => { it("does not owe a notice for the pre-dispatch claim or terminal outcomes", async () => { await installContextOnPendingFinal(); - // prepared -> unknown is the pre-I/O claim on every healthy send. + await settlePendingFinalDelivery(completion, "queued", ["prepared"]); await settlePendingFinalDelivery(completion, "unknown", ["prepared", "queued"]); await settlePendingFinalDelivery(completion, "delivered"); diff --git a/src/infra/outbound/delivery-completion.ts b/src/infra/outbound/delivery-completion.ts index 6cce7418562d..78a13b0241db 100644 --- a/src/infra/outbound/delivery-completion.ts +++ b/src/infra/outbound/delivery-completion.ts @@ -94,9 +94,6 @@ export async function settlePendingFinalDelivery( current === "suppressed" || (current === "unknown" && state === "unknown"); settled = terminal ? current : state; - // Unknown affirmed after a claimed send is ambiguity the user must hear - // about: record durable notice debt for the next same-route turn. The - // prepared->unknown transition is the pre-I/O claim and never owes one. const pending = internalEntry.pendingFinalDelivery; const existingNotice = internalEntry.pendingDeliveryNotice; const owedNotice = @@ -115,7 +112,13 @@ export async function settlePendingFinalDelivery( }, } : undefined; - if (settled === current && !owedNotice) { + const clearsNotice = + settled !== "queued" && + settled !== "unknown" && + existingNotice?.intentId === pending.intentId; + // The pre-I/O claim preserves crash-window ambiguity. Any authoritative + // fate for that intent must clear debt before a later turn can surface it. + if (settled === current && !owedNotice && !clearsNotice) { return null; } wakeRecovery = @@ -135,7 +138,7 @@ export async function settlePendingFinalDelivery( ...internalEntry.pendingFinalDelivery, deliveries: deliveries.with(index, { id: completion.deliveryId, state: settled }), }, - ...owedNotice, + ...(clearsNotice ? { pendingDeliveryNotice: undefined } : owedNotice), updatedAt: Date.now(), }; }, From 7ecad45a7dde8fc58ef3dfd543f7a646f0695a37 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 21:57:46 -0700 Subject: [PATCH 018/165] refactor(context-engine): retire legacy host param default (#122434) --- .../agent-harness-runtime.json | 2 +- .../agent-harness.json | 2 +- .../agent-runtime.json | 2 +- .../plugin-sdk-api-baseline/channel-core.json | 2 +- .../channel-entry-contract.json | 2 +- .../channel-message.json | 2 +- .../channel-outbound.json | 2 +- .../channel-plugin-common.json | 2 +- .../config-mutation.json | 2 +- .../config-runtime.json | 2 +- .../plugin-sdk-api-baseline/core.json | 2 +- .../plugin-sdk-api-baseline/discord.json | 2 +- .../inbound-reply-dispatch.json | 2 +- .../meeting-runtime.json | 2 +- .../model-session-runtime.json | 2 +- .../plugin-sdk-api-baseline/plugin-entry.json | 2 +- .../plugin-runtime.json | 2 +- .../provider-auth.json | 2 +- .../provider-catalog-runtime.json | 2 +- .../plugin-sdk-api-baseline/tool-plugin.json | 2 +- .../webhook-ingress.json | 2 +- docs/concepts/context-engine.md | 16 ++++----- docs/plugins/sdk-migration.md | 18 +++++----- docs/plugins/sdk-overview.md | 8 ++--- .../host-param-projection.test.ts | 36 +++---------------- src/context-engine/registry.ts | 12 +------ src/plugins/compat/registry-records.ts | 11 +++--- src/plugins/compat/registry.test.ts | 10 +++--- 28 files changed, 57 insertions(+), 96 deletions(-) diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json index 57dac44fd419..ba22e9cb9f50 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json @@ -1 +1 @@ -{"contentHash":"606504bb06b321f5a4fef507f322c297a9295dccdc2e5996ac64603049113408","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} +{"contentHash":"48dad42d04caeb62f04f9dbe32b4562ecef695e9f0c97fb891040408400f37bd","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json index 2a8b60ee0264..69b4ae7e72f2 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json @@ -1 +1 @@ -{"contentHash":"40d137a31b2ac9f1da776aafcc77b54422b1610c91fe2d6594068e1f7285e91b","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} +{"contentHash":"3d1c84bcc585b57a93054889e16fb3be02ff4d599d7d2a0566df6f463f2254a8","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json index 61def1e61738..ce3ba2b55349 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json @@ -1 +1 @@ -{"contentHash":"6667d863dee0c991c58196b0a77fa812fc1800fca9885c866abd04f3df1a03ce","entrypoint":"agent-runtime","importSpecifier":"openclaw/plugin-sdk/agent-runtime"} +{"contentHash":"fac71b2c80db2874419a589646fd560e8a8ad43dba93f5a6d26a73c171a0b4ba","entrypoint":"agent-runtime","importSpecifier":"openclaw/plugin-sdk/agent-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-core.json b/docs/.generated/plugin-sdk-api-baseline/channel-core.json index 156c909f3056..fdf18fa93eb5 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-core.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-core.json @@ -1 +1 @@ -{"contentHash":"6257c43a60153049dac1af0d828435081f10f6bcd2554e2a67d1c8adb6df973c","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} +{"contentHash":"4245891bae7517cf001f637e80d1d813c11385d695eebbd69a61258e83399c4e","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json index 876806d33a11..7dd5ca16f266 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json @@ -1 +1 @@ -{"contentHash":"88113b5ae8119ca780a3d93b0e033c87d0c387b21a29b72e72b375f5c77f08b3","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} +{"contentHash":"f719599ed89a658109698bc1ef1309e1709e5ae3385b7ce3f1c583343ea23b33","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-message.json b/docs/.generated/plugin-sdk-api-baseline/channel-message.json index 12d12f0322ff..86450cb57afe 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-message.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-message.json @@ -1 +1 @@ -{"contentHash":"a85b4bbcd416a76bde8d58af34fab58bdb416a1b2c8476b46a3ffd8540754e04","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} +{"contentHash":"d531b32d0544c42f375f628bd7a6b3d3582a91078db37bc048af7c3f23a9e59f","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json index 051fa3974425..b8ae76a44c49 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json @@ -1 +1 @@ -{"contentHash":"12e07b9ba7b5b35c1f4e0f4510a073adac00671d292a72700025c86376db22b0","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} +{"contentHash":"40b25681a1ee102cf1d2d5b23a29f96e2501ea521404deed59303e59c35089ec","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json index 41cf20d4e926..ff23b7afdb69 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json @@ -1 +1 @@ -{"contentHash":"f36ace33d1e16649ed888032751d5db67e826cdc59f06732a5c13b5185f971ed","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} +{"contentHash":"67884fcf5fc91b8b40a3c83e83080e69f54f7750cdd780368af63363f84ddc40","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} diff --git a/docs/.generated/plugin-sdk-api-baseline/config-mutation.json b/docs/.generated/plugin-sdk-api-baseline/config-mutation.json index 9106b41a163f..f7ad9d6ff24a 100644 --- a/docs/.generated/plugin-sdk-api-baseline/config-mutation.json +++ b/docs/.generated/plugin-sdk-api-baseline/config-mutation.json @@ -1 +1 @@ -{"contentHash":"b70eb302db749674e237eb2d740dacca2c20f883cd7f0581299cf010d3a71863","entrypoint":"config-mutation","importSpecifier":"openclaw/plugin-sdk/config-mutation"} +{"contentHash":"a7c63538d37122bfe240f75944916a3f01806f7fb7de3ecb976c6fd3f5dcd72e","entrypoint":"config-mutation","importSpecifier":"openclaw/plugin-sdk/config-mutation"} diff --git a/docs/.generated/plugin-sdk-api-baseline/config-runtime.json b/docs/.generated/plugin-sdk-api-baseline/config-runtime.json index 7123ed1c0dbf..6cc903f9d13d 100644 --- a/docs/.generated/plugin-sdk-api-baseline/config-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/config-runtime.json @@ -1 +1 @@ -{"contentHash":"4339bf4856bafcbf691b25df94a564a9b7bde09c041b9c0b31df3636a6e58462","entrypoint":"config-runtime","importSpecifier":"openclaw/plugin-sdk/config-runtime"} +{"contentHash":"3f128cc41bb2e44b40402774acd3a967501c72ae5d7b2f9d149a262cc0d5a2da","entrypoint":"config-runtime","importSpecifier":"openclaw/plugin-sdk/config-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/core.json b/docs/.generated/plugin-sdk-api-baseline/core.json index 775825f24dd0..12f84c8b1167 100644 --- a/docs/.generated/plugin-sdk-api-baseline/core.json +++ b/docs/.generated/plugin-sdk-api-baseline/core.json @@ -1 +1 @@ -{"contentHash":"7451e2a5ffc615f6e8fedebbf4327caf3a64a30973828ca776ca8e298052eebf","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} +{"contentHash":"ab54be164a2b0affece4d6c196ee64ae9259cac072d4ac6c32dd27daf4941565","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/discord.json b/docs/.generated/plugin-sdk-api-baseline/discord.json index 4be0b091d72d..b8fce271f0c0 100644 --- a/docs/.generated/plugin-sdk-api-baseline/discord.json +++ b/docs/.generated/plugin-sdk-api-baseline/discord.json @@ -1 +1 @@ -{"contentHash":"726e1cc6c7c0463333587b25908a0b4274c9ca2e1c7d696ab7af5cb392aeca07","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} +{"contentHash":"21823a6741645b81797b4be6bf16a2d067e7e2a007177fbc5c7a6cab98b08027","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} diff --git a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json index d84bd6799495..430076fe058e 100644 --- a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json +++ b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json @@ -1 +1 @@ -{"contentHash":"da9273b6213137fdfc3c2f0f22de681c7bd664dfb4fd0fd0f7636b70cad9835b","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} +{"contentHash":"80686774b5023519466038e4a20604d9efce462b0cd2915ab5597fb1087ef8af","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} diff --git a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json index d024143ffc6d..539f07550335 100644 --- a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json @@ -1 +1 @@ -{"contentHash":"2328445ee010703050ecce3ea4b823881172b1da8ffd061cb149a7324ac3b967","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} +{"contentHash":"9eb227dd27a3d08b868b1144bd64e1ff22da707af353699b9eb0f6438d4d98c1","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/model-session-runtime.json b/docs/.generated/plugin-sdk-api-baseline/model-session-runtime.json index de80d5630d4c..e1e954a02924 100644 --- a/docs/.generated/plugin-sdk-api-baseline/model-session-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/model-session-runtime.json @@ -1 +1 @@ -{"contentHash":"b1b9afd14967ec92dad01bc0a00997b578b9c4ca0f8601597fc58b503fc13606","entrypoint":"model-session-runtime","importSpecifier":"openclaw/plugin-sdk/model-session-runtime"} +{"contentHash":"ecb40006fc5ea974a3e31d0782c86e50c054e19164f864a564bb6f3f3d00dae9","entrypoint":"model-session-runtime","importSpecifier":"openclaw/plugin-sdk/model-session-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json index a7e49f33706f..ecfbe38df1a8 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json @@ -1 +1 @@ -{"contentHash":"cd50a67407a27b36d6f3e22af00940d1031bfe907fc15be5a72187e68f04d822","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} +{"contentHash":"696f33ed5d8f059b82ff4159183b80f7e4af086abb2383bae5c02d909427fe43","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json index 79ea9f3b1493..3b669bec3c96 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json @@ -1 +1 @@ -{"contentHash":"ba7ea5cfd334e44f5c5c2571a2161961a44f51e64e45074917fab3e69ac7652f","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} +{"contentHash":"411769ac67fd1a5b0ea4ada41b45678688e86194d03adc8d8efcad65c5f0c38c","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/provider-auth.json b/docs/.generated/plugin-sdk-api-baseline/provider-auth.json index e0d55cfede16..11124ace8d6d 100644 --- a/docs/.generated/plugin-sdk-api-baseline/provider-auth.json +++ b/docs/.generated/plugin-sdk-api-baseline/provider-auth.json @@ -1 +1 @@ -{"contentHash":"7233a8bb04605b4022cb18569b93f062d4f7986ae5ab5dd09e6c655984b56542","entrypoint":"provider-auth","importSpecifier":"openclaw/plugin-sdk/provider-auth"} +{"contentHash":"d56a974704a97ae438b03ba82aa84314e77bf65a7e7dd9096fd2ab2bc8cbcbec","entrypoint":"provider-auth","importSpecifier":"openclaw/plugin-sdk/provider-auth"} diff --git a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json index 8dbf79d536d2..22f4ce4ef442 100644 --- a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json @@ -1 +1 @@ -{"contentHash":"6f6b852b66e41c6f2c15b617bc00148efbafc2d737049b19b45fe3b25eebb9fe","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} +{"contentHash":"6539e277a49a27344f2844bcce06f609c5e463bb5a9be9eb1532994f9fec6479","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json index e7cf05ffec50..06bfdb667c76 100644 --- a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json +++ b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json @@ -1 +1 @@ -{"contentHash":"0686a3b02b9bae23e46af30fdddf46487db53ec6ffe0833ce9cf298aded54362","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} +{"contentHash":"9d1c23c498e989db4592749e735d0a09fc41ffeb86ab66f70b6894a2161e1212","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} diff --git a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json index 3e29106b8dd2..e25b523b4985 100644 --- a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json +++ b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json @@ -1 +1 @@ -{"contentHash":"80e15361b1e42280548074fc349fd32a45b55dd622c33bc37a0e2db963852790","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} +{"contentHash":"d0b42cb31d5b2e84acb3a63ca79fdd2bc988bde3505de54dc07dd85bb76fd60c","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} diff --git a/docs/concepts/context-engine.md b/docs/concepts/context-engine.md index 03ca332eb3fc..674dd5223887 100644 --- a/docs/concepts/context-engine.md +++ b/docs/concepts/context-engine.md @@ -213,13 +213,13 @@ Required members: | `assemble(params)` | Method | Build context for a model run (returns `AssembleResult`) | | `compact(params)` | Method | Summarize/reduce context | -Set `info.acceptedHostParams` to the host-added lifecycle fields the engine -accepts. Current keys are `sessionKey`, `prompt`, `runtimeSettings`, +Set `info.acceptedHostParams` to restrict the host-added lifecycle fields the +engine receives. Current keys are `sessionKey`, `prompt`, `runtimeSettings`, `sessionTarget`, and `runtimeContext`. OpenClaw intersects the declaration with the fields available for each lifecycle method, so undeclared or unknown keys -are never injected. Engines without this declaration receive the pre-host-field -legacy parameter set through 2026-08-12; after that date, undeclared engines -receive every current host field. +are never injected. Engines without this declaration receive every current +host field; declare an explicit list, including `[]`, when the engine validates +a narrower input shape. For durable admitted turns, declare both transcript semantics: @@ -308,9 +308,9 @@ rendered directly to users and does not create a dedicated reporting surface. - `diagnostics`: closed fallback and degraded reason codes when known Fields that can be unknown are represented as `null`; discriminator fields such -as runtime mode and selection source remain non-nullable. Engines that accept -`runtimeSettings` must include it in `info.acceptedHostParams` during the -compatibility window. +as runtime mode and selection source remain non-nullable. Engines that restrict +host parameters and accept `runtimeSettings` must include it in +`info.acceptedHostParams`. ### Host requirements diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index 6cd730ef1aaf..98f5be775480 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -198,14 +198,14 @@ artifact reader count is zero. Audit the current migration queue with `pnpm plugins:boundary-report`: -| Flag | Effect | -| ------------------------------------------------------- | ------------------------------------------------------------------------------ | -| `--summary` (or `pnpm plugins:boundary-report:summary`) | Compact counts instead of full detail. | -| `--json` | Machine-readable report. | -| `--owner ` | Filter to one plugin or compatibility owner. | -| `--fail-on-cross-owner` | Exit non-zero on cross-owner reserved SDK imports. | -| `--fail-on-eligible-compat` | Exit non-zero when a deprecated compat record's `removeAfter` date has passed. | -| `--fail-on-unclassified-unused-reserved` | Exit non-zero on unused reserved SDK shims. | +| Flag | Effect | +| ------------------------------------------------------- | -------------------------------------------------------------------------- | +| `--summary` (or `pnpm plugins:boundary-report:summary`) | Compact counts instead of full detail. | +| `--json` | Machine-readable report. | +| `--owner ` | Filter to one plugin or compatibility owner. | +| `--fail-on-cross-owner` | Exit non-zero on cross-owner reserved SDK imports. | +| `--fail-on-eligible-compat` | Exit non-zero on or after a deprecated compat record's `removeAfter` date. | +| `--fail-on-unclassified-unused-reserved` | Exit non-zero on unused reserved SDK shims. | `pnpm plugins:boundary-report:ci` runs with all three fail flags. Deprecated records normally have an explicit `removeAfter` date. A contract tied to a @@ -1069,7 +1069,7 @@ apps own device capture/playback UX. | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Now** | Warning-capable deprecated surfaces emit runtime warnings; repository guards reject deprecated SDK imports from core and bundled plugins. | | **Pending owner decision** | Records without `removeAfter` or `removalGate` remain deprecated and ineligible until their owner publishes a gate. | -| **Each compat record's `removeAfter` date** | That dated surface becomes eligible for removal; `pnpm plugins:boundary-report --fail-on-eligible-compat` fails CI once the date passes. | +| **Each compat record's `removeAfter` date** | That dated surface becomes eligible for removal; `pnpm plugins:boundary-report --fail-on-eligible-compat` fails CI on or after that date. | | **Next Plugin SDK major** | `inbound-reply-dispatch` reaches its explicit `next-plugin-sdk-major` gate; it is not date-eligible before that version boundary. | The remaining public SDK subpaths below have registry-backed removal windows. diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index f674421fe98c..f14cff72dc0f 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -619,10 +619,10 @@ For an end-to-end authoring guide, see ### Exclusive slots -| Method | What it registers | -| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (one active at a time). Declare accepted host-added lifecycle fields with `info.acceptedHostParams`; undeclared engines receive the legacy field set through 2026-08-12, then receive all current host fields. | -| `api.registerMemoryCapability(capability)` | Unified memory capability | +| Method | What it registers | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Context engine (one active at a time). Use `info.acceptedHostParams` to restrict accepted host-added lifecycle fields; undeclared engines receive all current host fields. | +| `api.registerMemoryCapability(capability)` | Unified memory capability | To participate in durable admitted turns, context engines must declare `currentTurnFence: "before-current-turn-entry-v1"` and diff --git a/src/context-engine/host-param-projection.test.ts b/src/context-engine/host-param-projection.test.ts index 2945e43a87a6..8aefbad0c59a 100644 --- a/src/context-engine/host-param-projection.test.ts +++ b/src/context-engine/host-param-projection.test.ts @@ -128,27 +128,6 @@ describe("context-engine host parameter projection", () => { }); }); - it("uses the legacy parameter set for undeclared engines during the window", async () => { - vi.useFakeTimers(); - vi.setSystemTime(new Date("2026-07-29T12:00:00Z")); - const assembleCalls: Array> = []; - const compactCalls: Array> = []; - const engineId = registerProbeEngine({ assembleCalls, compactCalls }); - - await invokeHostParamMethods( - await resolveContextEngine({ plugins: { slots: { contextEngine: engineId } } }), - ); - - for (const call of [...assembleCalls, ...compactCalls]) { - expect(call).not.toHaveProperty("sessionKey"); - expect(call).not.toHaveProperty("runtimeSettings"); - } - expect(assembleCalls[0]).not.toHaveProperty("prompt"); - expect(compactCalls[0]).not.toHaveProperty("sessionTarget"); - expect(compactCalls[0]).not.toHaveProperty("runtimeContext"); - expect(compactCalls[0]).toHaveProperty("sessionId", "session-1"); - }); - it("projects host parameters on fresh logical-turn engines", async () => { const assembleCalls: Array> = []; const compactCalls: Array> = []; @@ -234,9 +213,7 @@ describe("context-engine host parameter projection", () => { ]); }); - it("passes every host parameter to fresh undeclared engines after the window", async () => { - vi.useFakeTimers(); - vi.setSystemTime(new Date("2026-08-13T00:00:00Z")); + it("passes every host parameter to fresh undeclared engines", async () => { const assembleCalls: Array> = []; const compactCalls: Array> = []; const engineId = registerProbeEngine({ assembleCalls, compactCalls }); @@ -265,15 +242,12 @@ describe("context-engine host parameter projection", () => { ]); }); - it("switches undeclared engines to full parameters after the window", async () => { - vi.useFakeTimers(); - vi.setSystemTime(new Date("2026-07-29T12:00:00Z")); + it("passes every host parameter to resolved undeclared engines", async () => { const assembleCalls: Array> = []; const compactCalls: Array> = []; const engineId = registerProbeEngine({ assembleCalls, compactCalls }); const engine = await resolveContextEngine({ plugins: { slots: { contextEngine: engineId } } }); - vi.setSystemTime(new Date("2026-08-13T00:00:00Z")); await invokeHostParamMethods(engine); expect(assembleCalls[0]).toMatchObject({ @@ -317,15 +291,13 @@ describe("context-engine host parameter projection", () => { }); it("does not mutate frozen engines reused by a factory", async () => { - vi.useFakeTimers(); - vi.setSystemTime(new Date("2026-07-29T12:00:00Z")); const engineId = `host-param-frozen-${++engineCounter}`; const assemble = vi.fn(async (params) => ({ messages: params.messages, estimatedTokens: 0, })); class FrozenProbeEngine implements ContextEngine { - readonly #info = { id: engineId, name: "Frozen Probe" }; + readonly #info = { id: engineId, name: "Frozen Probe", acceptedHostParams: [] }; get info() { return this.#info; @@ -346,7 +318,7 @@ describe("context-engine host parameter projection", () => { const first = await resolveContextEngine({ plugins: { slots: { contextEngine: engineId } } }); const second = await resolveContextEngine({ plugins: { slots: { contextEngine: engineId } } }); - expect(first.info).toEqual({ id: engineId, name: "Frozen Probe" }); + expect(first.info).toEqual({ id: engineId, name: "Frozen Probe", acceptedHostParams: [] }); await first.assemble({ sessionId: "session-1", sessionKey: "first", messages: [message] }); await second.assemble({ sessionId: "session-2", sessionKey: "second", messages: [message] }); diff --git a/src/context-engine/registry.ts b/src/context-engine/registry.ts index b499974bc010..26508562e5a9 100644 --- a/src/context-engine/registry.ts +++ b/src/context-engine/registry.ts @@ -2,7 +2,6 @@ import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js"; import type { OpenClawConfig } from "../config/types.js"; import { createAbortError } from "../infra/abort-signal.js"; -import { getPluginCompatRecord } from "../plugins/compat/registry.js"; import type { ContextEngineFactory, ContextEngineFactoryContext, @@ -55,20 +54,11 @@ type ResolvedContextEngineMetadata = { }; const resolvedEngineMetadata = new WeakMap(); -const legacyHostParamDefaultRemoveAfter = getPluginCompatRecord( - "context-engine-legacy-host-param-default", -).removeAfter; - function projectContextEngineHostParams( engine: ContextEngine, params: Record, ): Record { - // Removal(2026-08-12): undeclared engines get full params. - // Contract: context-engine-legacy-host-param-default. - const useLegacyDefault = - legacyHostParamDefaultRemoveAfter !== undefined && - new Date().toISOString().slice(0, 10) <= legacyHostParamDefaultRemoveAfter; - const accepted = engine.info.acceptedHostParams ?? (useLegacyDefault ? [] : undefined); + const accepted = engine.info.acceptedHostParams; if (!accepted) { return params; } diff --git a/src/plugins/compat/registry-records.ts b/src/plugins/compat/registry-records.ts index 52417921850a..333555f81311 100644 --- a/src/plugins/compat/registry-records.ts +++ b/src/plugins/compat/registry-records.ts @@ -13,18 +13,17 @@ export const PLUGIN_COMPAT_RECORDS = [ MEDIA_LEGACY_PROJECTION_COMPAT_RECORD, { code: "context-engine-legacy-host-param-default", - status: "deprecated", + status: "removed", owner: "sdk", introduced: "2026-07-29", - deprecated: "2026-07-29", - warningStarts: "2026-07-29", - removeAfter: "2026-08-12", replacement: - "declare `ContextEngineInfo.acceptedHostParams`; full host params after the window", + "`ContextEngineInfo.acceptedHostParams` for restricted projection; omitted declarations receive full host params", docsPath: "/concepts/context-engine#the-contextengine-interface", surfaces: ["ContextEngineInfo.acceptedHostParams and undeclared-engine default projection"], - diagnostics: ["plugin compatibility registry and dated runtime removal marker"], + diagnostics: ["plugin compatibility registry and context engine guide"], tests: ["src/context-engine/host-param-projection.test.ts"], + releaseNote: + "The undeclared context-engine host-parameter compatibility default was removed; engines without `acceptedHostParams` now receive all current host fields.", }, { code: "removed-global-api-provider-publication", diff --git a/src/plugins/compat/registry.test.ts b/src/plugins/compat/registry.test.ts index b728f341abe8..cc8ac652cc36 100644 --- a/src/plugins/compat/registry.test.ts +++ b/src/plugins/compat/registry.test.ts @@ -176,17 +176,17 @@ describe("plugin compatibility registry", () => { ); }); - it("tracks the context-engine legacy host-param default through its two-week window", () => { + it("keeps the removed context-engine host-param default as a migration tombstone", () => { const record = listPluginCompatRecords().find( (candidate) => candidate.code === "context-engine-legacy-host-param-default", ); expect(record).toMatchObject({ - status: "deprecated", - deprecated: "2026-07-29", - warningStarts: "2026-07-29", - removeAfter: "2026-08-12", + status: "removed", + replacement: + "`ContextEngineInfo.acceptedHostParams` for restricted projection; omitted declarations receive full host params", }); + expect(record?.removeAfter).toBeUndefined(); }); it("keeps deprecated explicit target parser calls inside compatibility shims", () => { From dac940bf3a528334647dd69a8768545ba38949b2 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 22:06:53 -0700 Subject: [PATCH 019/165] refactor(openai): split realtime voice by layer (#122414) * refactor(openai): split realtime voice by layer * refactor(openai): delete dead realtime auth branches * chore(lint): ratchet max-lines baseline after realtime-voice split * style(openai): prune split leftovers --- config/max-lines-baseline.txt | 2 - .../realtime-voice-bridge-connection.test.ts | 748 +++ .../realtime-voice-bridge-events.test.ts | 678 +++ .../realtime-voice-bridge-reconnect.test.ts | 560 +++ .../realtime-voice-bridge-tools.test.ts | 697 +++ extensions/openai/realtime-voice-bridge.ts | 700 +++ .../realtime-voice-browser-auth.test.ts | 762 +++ extensions/openai/realtime-voice-events.ts | 402 ++ extensions/openai/realtime-voice-protocol.ts | 417 ++ .../realtime-voice-provider-routing.test.ts | 756 +++ .../openai/realtime-voice-provider.test.ts | 4259 ----------------- extensions/openai/realtime-voice-provider.ts | 2105 +------- .../realtime-voice-response-control.test.ts | 648 +++ .../openai/realtime-voice-session-policy.ts | 643 +++ .../openai/realtime-voice-test-support.ts | 318 ++ 15 files changed, 7360 insertions(+), 6335 deletions(-) create mode 100644 extensions/openai/realtime-voice-bridge-connection.test.ts create mode 100644 extensions/openai/realtime-voice-bridge-events.test.ts create mode 100644 extensions/openai/realtime-voice-bridge-reconnect.test.ts create mode 100644 extensions/openai/realtime-voice-bridge-tools.test.ts create mode 100644 extensions/openai/realtime-voice-bridge.ts create mode 100644 extensions/openai/realtime-voice-browser-auth.test.ts create mode 100644 extensions/openai/realtime-voice-events.ts create mode 100644 extensions/openai/realtime-voice-protocol.ts create mode 100644 extensions/openai/realtime-voice-provider-routing.test.ts delete mode 100644 extensions/openai/realtime-voice-provider.test.ts create mode 100644 extensions/openai/realtime-voice-response-control.test.ts create mode 100644 extensions/openai/realtime-voice-session-policy.ts create mode 100644 extensions/openai/realtime-voice-test-support.ts diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt index ebe7313541c6..73252121c10b 100644 --- a/config/max-lines-baseline.txt +++ b/config/max-lines-baseline.txt @@ -182,8 +182,6 @@ extensions/openai/image-generation-provider.test.ts extensions/openai/image-generation-provider.ts extensions/openai/openai-provider.test.ts extensions/openai/openai-provider.ts -extensions/openai/realtime-voice-provider.test.ts -extensions/openai/realtime-voice-provider.ts extensions/openrouter/index.test.ts extensions/openshell/src/backend.ts extensions/openshell/src/openshell-core.test.ts diff --git a/extensions/openai/realtime-voice-bridge-connection.test.ts b/extensions/openai/realtime-voice-bridge-connection.test.ts new file mode 100644 index 000000000000..0d0ab8002813 --- /dev/null +++ b/extensions/openai/realtime-voice-bridge-connection.test.ts @@ -0,0 +1,748 @@ +// Openai tests cover realtime voice provider plugin behavior. +import { REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ } from "openclaw/plugin-sdk/realtime-voice"; +import type { RealtimeVoiceBridge } from "openclaw/plugin-sdk/realtime-voice"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { buildOpenAIRealtimeVoiceProvider } from "./realtime-voice-provider.js"; + +const INTERNAL_REALTIME_VOICE_PROVIDER = Symbol.for("openclaw.internal.realtime-voice-provider.v1"); + +function readInternalRealtimeVoiceProviderApi(provider: object) { + return Reflect.get(provider, INTERNAL_REALTIME_VOICE_PROVIDER) as { + isBrowserSessionConfigured: (ctx: { + cfg?: object; + providerConfig: Record; + agentId?: string; + }) => boolean; + isGatewayRelayConfigured: (ctx: { + cfg?: object; + providerConfig: Record; + agentId?: string; + }) => boolean | undefined; + resolveBrowserSessionCapabilities: (ctx: { + cfg?: object; + providerConfig: Record; + model?: string; + }) => { + handlesAgentConsult?: boolean; + supportsToolCalls?: boolean; + supportsVideoFrames?: boolean; + supportsGatewayControl?: boolean; + transports?: string[]; + }; + resolveGatewayRelayCapabilities: (ctx: { + cfg?: object; + providerConfig: Record; + model?: string; + }) => { + handlesAgentConsult?: boolean; + supportsToolCalls?: boolean; + transports?: string[]; + }; + validateGatewayRelayLaunch: (ctx: { + cfg?: object; + providerConfig: Record; + model?: string; + autoRespondToAudio?: boolean; + }) => string | undefined; + cancelBrowserSession: (request: Record, session: object) => Promise; + }; +} + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + parseSent, + createNativeBridge, + requireSocket, + beginBridgeConnection, + openSocket, + emitServerEvent, + emitSessionUpdated, + connectReadyBridge, + expectedResponseCreateEvent, + requireRecord, + requireNestedRecord, + expectRecordFields, + requireSession, + createRealtimeTool, + createUnreadableToolName, + createMalformedToolName, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice bridge connection", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("adds OpenClaw attribution headers to native realtime websocket requests", () => { + vi.stubEnv("OPENCLAW_VERSION", "2026.3.22"); + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + providerConfig: { apiKey: "test-api-key-test" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + void bridge.connect(); + bridge.close(); + + const socket = FakeWebSocket.instances[0]; + const options = socket?.args[1] as + | { headers?: Record; maxPayload?: number } + | undefined; + expectRecordFields(options?.headers, "websocket headers", { + originator: "openclaw", + version: "2026.3.22", + "User-Agent": "openclaw/2026.3.22", + }); + expect(options?.headers).not.toHaveProperty("OpenAI-Beta"); + expect(options?.maxPayload).toBe(16 * 1024 * 1024); + }); + + it("sends one shared GA policy and waits for session.updated on an attached sideband", async () => { + const createBrowserSession = vi.fn( + async (_request: unknown, _auth: unknown) => + ({ + provider: "openai", + transport: "webrtc" as const, + clientSecret: "gateway-token", + offerUrl: "/plugins/openai/realtime/calls", + }) as const, + ); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { handlesAgentConsult: true as const }, + createBrowserSession, + cancelBrowserSession: vi.fn(async () => undefined), + }, + }); + const bindBridge = vi.fn(); + const onEvent = vi.fn(); + const onReady = vi.fn(); + const cfg = {} as never; + + expect( + readInternalRealtimeVoiceProviderApi(provider).resolveBrowserSessionCapabilities({ + cfg, + providerConfig: { apiKey: "test-api-key-platform" }, + model: "gpt-realtime-2.1", + }), + ).toMatchObject({ supportsGatewayControl: true }); + await expect( + provider.createBrowserSession?.({ + cfg, + providerConfig: { apiKey: "test-api-key-platform" }, + instructions: "Stay concise.", + model: "gpt-realtime-2.1", + prefixPaddingMs: 420, + reasoningEffort: "medium", + silenceDurationMs: 650, + tools: [createRealtimeTool("openclaw_agent_consult")], + vadThreshold: 0.7, + voice: "marin", + gatewayControl: { bindBridge, onEvent, onReady }, + }), + ).resolves.toMatchObject({ + clientSecret: "gateway-token", + offerUrl: "/plugins/openai/realtime/calls", + }); + const brokerRequest = requireRecord(createBrowserSession.mock.calls[0]?.[0], "broker request"); + expect(createBrowserSession.mock.calls[0]?.[1]).toEqual({ + type: "api-key", + token: "test-api-key-platform", + }); + const gaSideband = requireRecord(brokerRequest.gaSideband, "GA sideband request"); + expect(gaSideband.session).toMatchObject({ + type: "realtime", + instructions: "Stay concise.", + model: "gpt-realtime-2.1", + output_modalities: ["audio"], + reasoning: { effort: "medium" }, + tool_choice: "auto", + audio: { + input: { + format: { type: "audio/pcm", rate: 24000 }, + noise_reduction: { type: "near_field" }, + turn_detection: { + type: "server_vad", + threshold: 0.7, + prefix_padding_ms: 420, + silence_duration_ms: 650, + create_response: true, + interrupt_response: true, + }, + }, + output: { format: { type: "audio/pcm", rate: 24000 }, voice: "marin" }, + }, + }); + const createBridge = gaSideband.createBridge as (params: { + apiKey: string; + callId: string; + onTerminal: () => void; + }) => RealtimeVoiceBridge; + const bridge = createBridge({ + apiKey: "test-api-key-platform", + callId: "rtc_gateway", + onTerminal: vi.fn(), + }); + expect(bindBridge).toHaveBeenCalledWith(bridge); + const { connecting, socket } = beginBridgeConnection(bridge); + let connectResolved = false; + void connecting.then(() => { + connectResolved = true; + }); + expect(socket.args[0]).toBe("wss://api.openai.com/v1/realtime?call_id=rtc_gateway"); + openSocket(socket); + await Promise.resolve(); + const sessionUpdates = parseSent(socket).filter((event) => event.type === "session.update"); + expect(sessionUpdates).toHaveLength(1); + expect(sessionUpdates[0]?.session).toEqual(gaSideband.session); + emitServerEvent(socket, { + type: "session.created", + session: { type: "realtime", tools: [{ type: "function" }], tool_choice: "auto" }, + }); + await Promise.resolve(); + expect(connectResolved).toBe(false); + expect(onReady).not.toHaveBeenCalled(); + expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength(1); + emitSessionUpdated(socket); + await connecting; + expect(connectResolved).toBe(true); + expect(onReady).toHaveBeenCalledOnce(); + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "session.created", + detail: "tools=1 toolChoice=auto", + }); + bridge.close(); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + }); + + it("waits for session.updated before draining audio and firing onReady", async () => { + const onReady = vi.fn(); + const bridge = createNativeBridge({ + instructions: "Be helpful.", + language: "de", + onReady, + }); + const { connecting, socket } = beginBridgeConnection(bridge); + let connectResolved = false; + void connecting.then(() => { + connectResolved = true; + }); + + openSocket(socket); + await Promise.resolve(); + + bridge.sendAudio(Buffer.from("before-ready")); + emitServerEvent(socket, { type: "session.created" }); + + expect(connectResolved).toBe(false); + expect(onReady).not.toHaveBeenCalled(); + expect(parseSent(socket).map((event) => event.type)).toEqual(["session.update"]); + const session = requireSession(socket); + expectRecordFields(session, "session", { + type: "realtime", + model: "gpt-realtime-2.1", + output_modalities: ["audio"], + }); + const inputAudio = requireNestedRecord(session, ["audio", "input"]); + expectRecordFields(inputAudio, "session audio input", { + format: { type: "audio/pcmu" }, + noise_reduction: null, + transcription: { model: "gpt-4o-mini-transcribe", language: "de" }, + }); + expect(requireNestedRecord(session, ["audio", "output"])).toEqual({ + format: { type: "audio/pcmu" }, + voice: "alloy", + }); + expect(session).not.toHaveProperty("temperature"); + expect(bridge.isConnected()).toBe(false); + + emitSessionUpdated(socket); + await connecting; + + expect(connectResolved).toBe(true); + expect(onReady).toHaveBeenCalledTimes(1); + expect(parseSent(socket).map((event) => event.type)).toEqual([ + "session.update", + "input_audio_buffer.append", + ]); + expect(bridge.isConnected()).toBe(true); + }); + + it("bounds queued audio by aggregate bytes before session readiness", async () => { + const bridge = createNativeBridge(); + const { connecting, socket } = beginBridgeConnection(bridge); + openSocket(socket); + await Promise.resolve(); + + bridge.sendAudio(Buffer.alloc(512 * 1024, 0x01)); + bridge.sendAudio(Buffer.alloc(512 * 1024, 0x02)); + bridge.sendAudio(Buffer.from("overflow")); + emitSessionUpdated(socket); + await connecting; + + const audioEvents = parseSent(socket).filter( + (event) => event.type === "input_audio_buffer.append", + ); + expect(audioEvents).toHaveLength(2); + expect( + audioEvents.map((event) => Buffer.from(String(event.audio), "base64").byteLength), + ).toEqual([512 * 1024, 512 * 1024]); + bridge.close(); + }); + + it("discards audio closed before the first connection and reconnects fresh", async () => { + const onClose = vi.fn(); + const bridge = createNativeBridge({ onClose }); + + bridge.sendAudio(Buffer.from("queued-before-connect")); + bridge.close(); + bridge.close(); + bridge.sendAudio(Buffer.from("sent-after-close")); + + expect(FakeWebSocket.instances).toHaveLength(0); + expect(onClose).not.toHaveBeenCalled(); + + const { connecting, socket } = beginBridgeConnection(bridge); + openSocket(socket); + emitSessionUpdated(socket); + await connecting; + + expect( + parseSent(socket).filter((event) => event.type === "input_audio_buffer.append"), + ).toHaveLength(0); + + bridge.close(); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("completed"); + }); + + it("does not carry queued audio across terminal close and explicit reconnect", async () => { + const bridge = createNativeBridge(); + const { connecting: firstConnect, socket: firstSocket } = beginBridgeConnection(bridge); + openSocket(firstSocket); + await Promise.resolve(); + + bridge.sendAudio(Buffer.from("queued-before-close")); + bridge.close(); + await firstConnect; + bridge.sendAudio(Buffer.from("sent-after-close")); + + const { connecting: reconnecting, socket: secondSocket } = beginBridgeConnection(bridge, 1); + openSocket(secondSocket); + emitSessionUpdated(secondSocket); + await reconnecting; + + expect( + parseSent(secondSocket).filter((event) => event.type === "input_audio_buffer.append"), + ).toHaveLength(0); + bridge.close(); + }); + + it("shares an in-flight connection until session readiness", async () => { + const onReady = vi.fn(); + const bridge = createNativeBridge({ onReady }); + const firstConnect = bridge.connect(); + const secondConnect = bridge.connect(); + const socket = requireSocket(); + + expect(FakeWebSocket.instances).toHaveLength(1); + openSocket(socket); + emitSessionUpdated(socket); + + await Promise.all([firstConnect, secondConnect]); + expect(onReady).toHaveBeenCalledOnce(); + bridge.close(); + }); + + it("fails terminally when the readiness callback throws", async () => { + vi.useFakeTimers(); + const readyError = new Error("readiness callback failed"); + const onClose = vi.fn(); + const onError = vi.fn(); + const onReady = vi.fn(() => { + throw readyError; + }); + const bridge = createNativeBridge({ onClose, onError, onReady }); + const { connecting, socket } = beginBridgeConnection(bridge); + let connectError: unknown; + const observedConnect = connecting.catch((error: unknown) => { + connectError = error; + }); + + openSocket(socket); + bridge.sendAudio(Buffer.from("queued-before-ready")); + emitSessionUpdated(socket); + await vi.advanceTimersByTimeAsync(0); + const immediateConnectError = connectError; + + bridge.close(); + await observedConnect; + + expect(immediateConnectError).toBe(readyError); + expect(onReady).toHaveBeenCalledOnce(); + expect(onError).toHaveBeenCalledOnce(); + expect(onError).toHaveBeenCalledWith(readyError); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("error"); + expect(socket.closed).toBe(true); + expect(bridge.isConnected()).toBe(false); + expect( + parseSent(socket).filter((event) => event.type === "input_audio_buffer.append"), + ).toHaveLength(0); + + emitSessionUpdated(socket); + await expect(bridge.connect()).rejects.toBe(readyError); + expect(FakeWebSocket.instances).toHaveLength(1); + expect(onReady).toHaveBeenCalledOnce(); + expect(onError).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledOnce(); + }); + + it("omits unsupported OpenAI tool names from GA session updates", async () => { + const bridge = createNativeBridge({ + tools: [ + createRealtimeTool("1_lookup"), + createRealtimeTool("calendar.lookup:next"), + createRealtimeTool("bad/name"), + createRealtimeTool("x".repeat(65)), + createMalformedToolName(null), + createMalformedToolName(42), + createUnreadableToolName(), + ], + }); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + + const tools = requireSession(socket).tools as Array<{ name?: string }>; + expect(tools.map((tool) => tool.name)).toEqual(["1_lookup", "x".repeat(65)]); + emitSessionUpdated(socket); + await connecting; + }); + + it("keeps Azure deployment bridges on deployment-compatible session payloads", async () => { + const bridge = createNativeBridge({ + providerConfig: { + apiKey: "test-api-key-test", + azureEndpoint: "https://example.openai.azure.com/", + azureDeployment: "realtime-prod", + azureApiVersion: "2024-10-01-preview", + voice: "verse", + }, + audioFormat: REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, + instructions: "Be helpful.", + tools: [ + createRealtimeTool("1_lookup"), + createRealtimeTool("calendar.lookup:next"), + createRealtimeTool("x".repeat(65)), + ], + }); + const { connecting, socket } = beginBridgeConnection(bridge); + + expect(socket.args[0]).toBe( + "wss://example.openai.azure.com/openai/realtime?api-version=2024-10-01-preview&deployment=realtime-prod", + ); + + openSocket(socket); + await Promise.resolve(); + + const session = requireSession(socket); + expectRecordFields(session, "session", { + modalities: ["text", "audio"], + instructions: "Be helpful.", + voice: "verse", + input_audio_format: "pcm16", + output_audio_format: "pcm16", + input_audio_transcription: { model: "whisper-1" }, + temperature: 0.8, + }); + expectRecordFields( + requireRecord(session.turn_detection, "session turn detection"), + "turn detection", + { + create_response: true, + }, + ); + expect(session).not.toHaveProperty("type"); + expect(session).not.toHaveProperty("audio"); + const tools = session.tools as Array<{ name?: string }>; + expect(tools.map((tool) => tool.name)).toEqual(["1_lookup"]); + + emitSessionUpdated(socket); + await connecting; + + bridge.triggerGreeting?.("Say hello."); + expect(parseSent(socket).slice(-2)).toEqual([ + { + type: "session.update", + session: { + turn_detection: { + type: "server_vad", + threshold: 0.5, + prefix_padding_ms: 300, + silence_duration_ms: 500, + create_response: false, + }, + }, + }, + expectedResponseCreateEvent(), + ]); + + emitServerEvent(socket, { type: "response.done" }); + expect(parseSent(socket).at(-1)).toEqual({ + type: "session.update", + session: { + turn_detection: { + type: "server_vad", + threshold: 0.5, + prefix_padding_ms: 300, + silence_duration_ms: 500, + create_response: true, + }, + }, + }); + }); + + it("rejects connection when session configuration fails before readiness", async () => { + const bridge = createNativeBridge(); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { message: "invalid realtime session" }, + }), + ), + ); + + await expect(connecting).rejects.toThrow("invalid realtime session"); + expect(bridge.isConnected()).toBe(false); + }); + + it("rejects connection when the socket closes before session readiness", async () => { + const bridge = createNativeBridge(); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + socket.close(1006, "session closed"); + + await expect(connecting).rejects.toThrow("OpenAI realtime connection closed before ready"); + expect(bridge.isConnected()).toBe(false); + }); + + it("bounds sideband frames received before session readiness", async () => { + const bridge = createNativeBridge(); + const { connecting, socket } = beginBridgeConnection(bridge); + openSocket(socket); + const frame = Buffer.from( + JSON.stringify({ type: "session.created", padding: "x".repeat(600 * 1024) }), + ); + + socket.emit("message", frame); + socket.emit("message", frame); + + await expect(connecting).rejects.toThrow("sideband startup buffer exceeded"); + expect(bridge.isConnected()).toBe(false); + }); + + it("does not report startup timeout shutdown as a clean close", async () => { + vi.useFakeTimers(); + const onClose = vi.fn(); + const bridge = createNativeBridge({ onClose }); + const { connecting, socket } = beginBridgeConnection(bridge); + + const timeoutAssertion = expect(connecting).rejects.toThrow( + "OpenAI realtime connection timeout", + ); + await vi.advanceTimersByTimeAsync(10_000); + await timeoutAssertion; + expect(socket.terminated).toBe(true); + expect(onClose).not.toHaveBeenCalled(); + expect(FakeWebSocket.instances).toHaveLength(1); + expect(bridge.isConnected()).toBe(false); + }); + + it("can disable automatic audio turn responses for agent-routed voice loops", async () => { + const bridge = createNativeBridge({ + autoRespondToAudio: false, + }); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + emitSessionUpdated(socket); + await connecting; + + expectRecordFields( + requireNestedRecord(requireSession(socket), ["audio", "input", "turn_detection"]), + "turn detection", + { + create_response: false, + interrupt_response: false, + }, + ); + }); + + it("can disable realtime response interruption while keeping audio responses enabled", async () => { + const bridge = createNativeBridge({ + autoRespondToAudio: true, + interruptResponseOnInputAudio: false, + }); + const socket = await connectReadyBridge(bridge); + + expectRecordFields( + requireNestedRecord(requireSession(socket), ["audio", "input", "turn_detection"]), + "turn detection", + { + create_response: true, + interrupt_response: false, + }, + ); + }); + + it("can request PCM16 24 kHz realtime audio for Chrome command-pair bridges", async () => { + const bridge = createNativeBridge({ + audioFormat: REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, + }); + const socket = await connectReadyBridge(bridge); + + const session = requireSession(socket); + expect(requireNestedRecord(session, ["audio", "input", "format"])).toEqual({ + type: "audio/pcm", + rate: 24000, + }); + expect(requireNestedRecord(session, ["audio", "output", "format"])).toEqual({ + type: "audio/pcm", + rate: 24000, + }); + }); + + it("settles cleanly when closed before the websocket opens", async () => { + const onClose = vi.fn(); + const bridge = createNativeBridge({ onClose }); + const { connecting, socket } = beginBridgeConnection(bridge); + + bridge.close(); + bridge.close(); + + await expect(connecting).resolves.toBeUndefined(); + expect(socket.closed).toBe(true); + expect(socket.terminated).toBe(false); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("completed"); + }); +}); diff --git a/extensions/openai/realtime-voice-bridge-events.test.ts b/extensions/openai/realtime-voice-bridge-events.test.ts new file mode 100644 index 000000000000..c8f37527210c --- /dev/null +++ b/extensions/openai/realtime-voice-bridge-events.test.ts @@ -0,0 +1,678 @@ +// Openai tests cover realtime voice provider plugin behavior. +import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + parseSent, + createNativeBridge, + connectReadyBridge, + expectedResponseCancelEvent, + hasSentEventType, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice bridge events", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("does not locally clear playback on speech-start events when input interruption is disabled", async () => { + const onAudio = vi.fn(); + const onClearAudio = vi.fn(); + const bridge = createNativeBridge({ + autoRespondToAudio: true, + interruptResponseOnInputAudio: false, + onAudio, + onClearAudio, + }); + const socket = await connectReadyBridge(bridge); + + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "input_audio_buffer.speech_started" })), + ); + + expect(onAudio).toHaveBeenCalledTimes(1); + expect(onClearAudio).not.toHaveBeenCalled(); + expect(hasSentEventType(socket, "response.cancel")).toBe(false); + expect(hasSentEventType(socket, "conversation.item.truncate")).toBe(false); + }); + + it("keeps assistant playback active on server VAD when automatic audio responses are disabled", async () => { + const onAudio = vi.fn(); + const onClearAudio = vi.fn(); + const bridge = createNativeBridge({ + autoRespondToAudio: false, + onAudio, + onClearAudio, + }); + const socket = await connectReadyBridge(bridge); + + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "input_audio_buffer.speech_started" })), + ); + + expect(onAudio).toHaveBeenCalledTimes(1); + expect(onClearAudio).not.toHaveBeenCalled(); + expect(hasSentEventType(socket, "response.cancel")).toBe(false); + expect(hasSentEventType(socket, "conversation.item.truncate")).toBe(false); + }); + + it("truncates externally interrupted playback after an immediate mark acknowledgement", async () => { + const onAudio = vi.fn(); + const onClearAudio = vi.fn(); + const bridge = createNativeBridge({ + onAudio, + onClearAudio, + onMark: () => bridge.acknowledgeMark(), + }); + const socket = await connectReadyBridge(bridge); + + bridge.setMediaTimestamp(1000); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + bridge.setMediaTimestamp(1300); + + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + + expect(onAudio).toHaveBeenCalledTimes(1); + expect(onClearAudio).toHaveBeenCalledWith("barge-in"); + expect(parseSent(socket).slice(-2)).toEqual([ + expectedResponseCancelEvent(), + { + type: "conversation.item.truncate", + item_id: "item_1", + content_index: 0, + audio_end_ms: 300, + }, + ]); + }); + + it("preserves FIFO playback acknowledgements after sustained output", async () => { + const onClearAudio = vi.fn(); + const onMark = vi.fn(); + const bridge = createNativeBridge({ + onClearAudio, + onMark, + }); + const socket = await connectReadyBridge(bridge); + + bridge.setMediaTimestamp(1000); + for (let index = 0; index < 300; index += 1) { + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + } + + const marks = onMark.mock.calls.map(([markName]) => String(markName)); + expect(marks).toHaveLength(300); + for (let index = 0; index < 299; index += 1) { + bridge.acknowledgeMark(); + } + bridge.setMediaTimestamp(1300); + bridge.handleBargeIn?.(); + + expect(parseSent(socket).slice(-1)).toEqual([ + { + type: "conversation.item.truncate", + item_id: "item_1", + content_index: 0, + audio_end_ms: 300, + }, + ]); + expect(onClearAudio).toHaveBeenCalledWith("barge-in"); + + for (let index = 0; index < 300; index += 1) { + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + } + const latestMark = onMark.mock.calls.at(-1)?.[0]; + if (typeof latestMark !== "string") { + throw new Error("expected a playback mark"); + } + bridge.acknowledgeMark(latestMark); + bridge.setMediaTimestamp(1600); + bridge.handleBargeIn?.(); + + expect( + parseSent(socket).filter((event) => event.type === "conversation.item.truncate"), + ).toHaveLength(1); + bridge.close(); + }); + + it("treats a later named mark as cumulative playback progress", async () => { + const onMark = vi.fn(); + const bridge = createNativeBridge({ onMark }); + const socket = await connectReadyBridge(bridge); + + bridge.setMediaTimestamp(1000); + for (let index = 0; index < 3; index += 1) { + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + } + const marks = onMark.mock.calls.map(([markName]) => String(markName)); + expect(marks).toHaveLength(3); + + bridge.acknowledgeMark(marks[2]); + bridge.acknowledgeMark(marks[0]); + bridge.acknowledgeMark(marks[1]); + bridge.setMediaTimestamp(1300); + bridge.handleBargeIn?.(); + + expect( + parseSent(socket).filter((event) => event.type === "conversation.item.truncate"), + ).toHaveLength(0); + bridge.close(); + }); + + it("forwards current realtime output audio events", async () => { + const onAudio = vi.fn(); + const onTranscript = vi.fn(); + const bridge = createNativeBridge({ + onAudio, + onTranscript, + }); + const socket = await connectReadyBridge(bridge); + + const audio = Buffer.from("assistant audio"); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.output_audio.delta", + item_id: "item_1", + delta: audio.toString("base64"), + }), + ), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.output_audio_transcript.done", + transcript: "hello from current realtime events", + }), + ), + ); + + expect(onAudio).toHaveBeenCalledWith(audio); + expect(onTranscript).toHaveBeenCalledWith( + "assistant", + "hello from current realtime events", + true, + ); + }); + + it("surfaces input transcription failures with their provider error details", async () => { + const onError = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onError, onEvent }); + const socket = await connectReadyBridge(bridge); + + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "conversation.item.input_audio_transcription.failed", + item_id: "item_speech", + error: { code: "decoder_failure", message: "speech decoder exploded" }, + }), + ), + ); + + expect(onError).toHaveBeenCalledWith( + expect.objectContaining({ message: "speech decoder exploded" }), + ); + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "conversation.item.input_audio_transcription.failed", + itemId: "item_speech", + detail: "speech decoder exploded", + }); + }); + + it("preserves corrected final text from legacy realtime text events", async () => { + const onTranscript = vi.fn(); + const bridge = createNativeBridge({ onTranscript }); + const socket = await connectReadyBridge(bridge); + + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.text.delta", delta: "draft assistant" })), + ); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.text.done", text: "corrected assistant" })), + ); + + expect(onTranscript.mock.calls).toEqual([ + ["assistant", "draft assistant", false], + ["assistant", "corrected assistant", true], + ]); + }); + + it.each([ + ["invalid alphabet", "not-base64!"], + ["non-canonical pad bits", "ZE=="], + ])("terminates the session for %s in output audio", async (_scenario, delta) => { + const onAudio = vi.fn(); + const onError = vi.fn(); + const onClose = vi.fn(); + const bridge = createNativeBridge({ + onAudio, + onError, + onClose, + }); + const socket = await connectReadyBridge(bridge); + + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.output_audio.delta", + item_id: "item_1", + delta, + }), + ), + ); + + expect(onAudio).not.toHaveBeenCalled(); + expect(onError).toHaveBeenCalledWith( + expect.objectContaining({ + message: "OpenAI realtime stream returned malformed base64 audio data", + }), + ); + expect(onClose).toHaveBeenCalledWith("error"); + expect(socket.closed).toBe(true); + await expect(bridge.connect()).rejects.toThrow( + "OpenAI realtime stream returned malformed base64 audio data", + ); + }); + + it("forwards Codex-compatible legacy realtime audio and transcript events", async () => { + const onAudio = vi.fn(); + const onTranscript = vi.fn(); + const bridge = createNativeBridge({ + onAudio, + onTranscript, + }); + const socket = await connectReadyBridge(bridge); + + const audio = Buffer.from("legacy assistant audio"); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "conversation.output_audio.delta", + data: audio.toString("base64"), + sample_rate: 24000, + channels: 1, + }), + ), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "conversation.input_transcript.delta", + delta: "partial user", + }), + ), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "conversation.output_transcript.delta", + delta: "partial assistant", + }), + ), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.output_text.done", + text: "final assistant text", + }), + ), + ); + + expect(onAudio).toHaveBeenCalledWith(audio); + expect(onTranscript).toHaveBeenCalledWith("user", "partial user", false); + expect(onTranscript).toHaveBeenCalledWith("assistant", "partial assistant", false); + expect(onTranscript).toHaveBeenCalledWith("assistant", "final assistant text", true); + }); + + it("does not send duplicate response.cancel while cancellation is pending", async () => { + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onEvent }); + const socket = await connectReadyBridge(bridge); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + bridge.setMediaTimestamp(1000); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + bridge.setMediaTimestamp(1300); + + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + + expect(parseSent(socket).filter((event) => event.type === "response.cancel")).toHaveLength(1); + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "response.cancel", + detail: "reason=barge-in", + }); + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "conversation.item.truncate", + detail: "reason=barge-in audioEndMs=300", + }); + }); + + it("ignores zero-length playback barge-in without clearing audio", async () => { + const onClearAudio = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ + onClearAudio, + onEvent, + }); + const socket = await connectReadyBridge(bridge); + bridge.setMediaTimestamp(1000); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + + expect(onClearAudio).not.toHaveBeenCalled(); + expect(hasSentEventType(socket, "response.cancel")).toBe(false); + expect(parseSent(socket).some((event) => event.type === "conversation.item.truncate")).toBe( + false, + ); + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "conversation.item.truncate.skipped", + detail: "reason=barge-in audioEndMs=0 minAudioEndMs=250", + }); + }); + + it("force-cancels zero-length playback barge-in for agent handoff fallback", async () => { + const onClearAudio = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ + onClearAudio, + onEvent, + }); + const socket = await connectReadyBridge(bridge); + bridge.setMediaTimestamp(1000); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + + bridge.handleBargeIn?.({ audioPlaybackActive: true, force: true }); + + expect(parseSent(socket).slice(-2)).toEqual([ + expectedResponseCancelEvent(), + { + type: "conversation.item.truncate", + item_id: "item_1", + content_index: 0, + audio_end_ms: 0, + }, + ]); + expect(onClearAudio).toHaveBeenCalled(); + expect( + onEvent.mock.calls.some( + ([event]) => isRecord(event) && event.type === "conversation.item.truncate.skipped", + ), + ).toBe(false); + }); + + it("allows immediate playback barge-in when the minimum audio window is zero", async () => { + const onClearAudio = vi.fn(); + const bridge = createNativeBridge({ + providerConfig: { + apiKey: "test-api-key-test", + minBargeInAudioEndMs: 0, + }, + onClearAudio, + }); + const socket = await connectReadyBridge(bridge); + bridge.setMediaTimestamp(1000); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + + expect(onClearAudio).toHaveBeenCalledWith("barge-in"); + expect(parseSent(socket).slice(-2)).toEqual([ + expectedResponseCancelEvent(), + { + type: "conversation.item.truncate", + item_id: "item_1", + content_index: 0, + audio_end_ms: 0, + }, + ]); + }); +}); diff --git a/extensions/openai/realtime-voice-bridge-reconnect.test.ts b/extensions/openai/realtime-voice-bridge-reconnect.test.ts new file mode 100644 index 000000000000..4ac6a8c0264b --- /dev/null +++ b/extensions/openai/realtime-voice-bridge-reconnect.test.ts @@ -0,0 +1,560 @@ +// Openai tests cover realtime voice provider plugin behavior. +import type { RealtimeVoiceBridgeEvent } from "openclaw/plugin-sdk/realtime-voice"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const OPENAI_REALTIME_REJECTED_KEY_MESSAGE = + "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source"; + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + parseSent, + createNativeBridge, + requireSocket, + beginBridgeConnection, + openSocket, + emitServerEvent, + emitSessionUpdated, + emitCompletedToolCalls, + emitFunctionOutputAdded, + connectReadyBridge, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice bridge reconnect", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("rotates realtime bridges on provider max-duration events without reporting an error", async () => { + vi.useFakeTimers(); + const onError = vi.fn(); + const onEvent = vi.fn(); + const onReady = vi.fn(); + const bridge = createNativeBridge({ onError, onEvent, onReady }); + const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); + + openSocket(firstSocket); + emitSessionUpdated(firstSocket); + await connecting; + expect(onReady).toHaveBeenCalledOnce(); + + firstSocket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { message: "Your session hit the maximum duration of 60 minutes." }, + }), + ), + ); + + expect(onError).not.toHaveBeenCalled(); + expect(firstSocket.closed).toBe(true); + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "session.rotation", + detail: "reason=max-duration", + }); + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "session.reconnect.scheduled", + detail: "reason=max-duration attempt=1 delayMs=1000", + }); + + await vi.advanceTimersByTimeAsync(1000); + await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2)); + const secondSocket = requireSocket(1); + openSocket(secondSocket); + emitSessionUpdated(secondSocket); + + await vi.waitFor(() => + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "session.rotation.ready", + detail: "reason=max-duration", + }), + ); + await vi.waitFor(() => + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "session.reconnect.ready", + detail: "reason=max-duration attempt=1", + }), + ); + expect(bridge.isConnected()).toBe(true); + expect(onReady).toHaveBeenCalledOnce(); + + bridge.close(); + }); + + it("clears canceled rotation metadata before an explicit reconnect", async () => { + vi.useFakeTimers(); + const onClose = vi.fn(); + const onError = vi.fn(); + const onEvent = vi.fn(); + const onReady = vi.fn(); + const bridge = createNativeBridge({ onClose, onError, onEvent, onReady }); + const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); + + firstSocket.deferClose = true; + openSocket(firstSocket); + emitSessionUpdated(firstSocket); + await connecting; + expect(onReady).toHaveBeenCalledOnce(); + + emitServerEvent(firstSocket, { + type: "error", + error: { message: "Your session hit the maximum duration of 60 minutes." }, + }); + expect(firstSocket.closed).toBe(true); + + bridge.close(); + bridge.close(); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("completed"); + + const { connecting: reconnecting, socket: secondSocket } = beginBridgeConnection(bridge, 1); + firstSocket.emitDeferredClose(); + openSocket(secondSocket); + emitSessionUpdated(secondSocket); + await reconnecting; + + expect(onReady).toHaveBeenCalledTimes(2); + expect(onEvent).not.toHaveBeenCalledWith( + expect.objectContaining({ type: "session.rotation.ready" }), + ); + expect(onError).not.toHaveBeenCalled(); + + secondSocket.readyState = FakeWebSocket.CLOSED; + secondSocket.emit("close", 1006, Buffer.from("ordinary drop")); + await vi.advanceTimersByTimeAsync(0); + + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "session.reconnect.scheduled", + detail: "reason=websocket-close attempt=1 delayMs=1000", + }); + expect(onEvent).not.toHaveBeenCalledWith( + expect.objectContaining({ + type: "session.reconnect.scheduled", + detail: expect.stringContaining("reason=max-duration"), + }), + ); + + bridge.close(); + await vi.advanceTimersByTimeAsync(0); + expect(vi.getTimerCount()).toBe(0); + expect(onClose).toHaveBeenCalledTimes(2); + expect(onClose).toHaveBeenLastCalledWith("completed"); + }); + + it("cancels a pending reconnect and allows a later explicit connect", async () => { + vi.useFakeTimers(); + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + emitSessionUpdated(socket); + await connecting; + + socket.readyState = FakeWebSocket.CLOSED; + socket.emit("close", 1006, Buffer.from("transient drop")); + await vi.advanceTimersByTimeAsync(0); + expect(vi.getTimerCount()).toBe(1); + + bridge.close(); + await vi.advanceTimersByTimeAsync(0); + + expect(vi.getTimerCount()).toBe(0); + expect(FakeWebSocket.instances).toHaveLength(1); + expect(onError).not.toHaveBeenCalled(); + + const { connecting: reconnecting, socket: reconnectedSocket } = beginBridgeConnection( + bridge, + 1, + ); + openSocket(reconnectedSocket); + emitSessionUpdated(reconnectedSocket); + await reconnecting; + + expect(bridge.isConnected()).toBe(true); + expect(FakeWebSocket.instances).toHaveLength(2); + expect(onError).not.toHaveBeenCalled(); + bridge.close(); + }); + + it("does not report reconnect readiness after cancellation during provider setup", async () => { + vi.useFakeTimers(); + const onClose = vi.fn(); + const onError = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onClose, onError, onEvent }); + const socket = await connectReadyBridge(bridge); + + socket.readyState = FakeWebSocket.CLOSED; + socket.emit("close", 1006, Buffer.from("transient drop")); + await vi.advanceTimersByTimeAsync(1000); + const retrySocket = requireSocket(1); + openSocket(retrySocket); + + bridge.close(); + await vi.advanceTimersByTimeAsync(0); + + expect(onEvent).not.toHaveBeenCalledWith( + expect.objectContaining({ type: "session.reconnect.ready" }), + ); + expect(onError).not.toHaveBeenCalled(); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("completed"); + }); + + it("lets cancellation win a queued reconnect startup error", async () => { + vi.useFakeTimers(); + const onClose = vi.fn(); + const onError = vi.fn(); + const bridge = createNativeBridge({ onClose, onError }); + const socket = await connectReadyBridge(bridge); + + socket.readyState = FakeWebSocket.CLOSED; + socket.emit("close", 1006, Buffer.from("transient drop")); + await vi.advanceTimersByTimeAsync(1000); + const retrySocket = requireSocket(1); + openSocket(retrySocket); + emitServerEvent(retrySocket, { + type: "error", + error: { message: "queued retry startup failure" }, + }); + + bridge.close(); + await vi.advanceTimersByTimeAsync(0); + + expect(onError).not.toHaveBeenCalled(); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("completed"); + expect(vi.getTimerCount()).toBe(0); + }); + + it("reports one terminal error for malformed audio during reconnect setup", async () => { + vi.useFakeTimers(); + const onClose = vi.fn(); + const onError = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onClose, onError, onEvent }); + const socket = await connectReadyBridge(bridge); + + socket.readyState = FakeWebSocket.CLOSED; + socket.emit("close", 1006, Buffer.from("transient drop")); + await vi.advanceTimersByTimeAsync(1000); + const retrySocket = requireSocket(1); + openSocket(retrySocket); + emitServerEvent(retrySocket, { + type: "response.output_audio.delta", + item_id: "item_1", + delta: "not-base64!", + }); + await vi.advanceTimersByTimeAsync(0); + + expect(onError).toHaveBeenCalledOnce(); + expect(onError).toHaveBeenCalledWith( + new Error("OpenAI realtime stream returned malformed base64 audio data"), + ); + expect(onClose).toHaveBeenCalledOnce(); + expect(onClose).toHaveBeenCalledWith("error"); + expect(onEvent).not.toHaveBeenCalledWith( + expect.objectContaining({ type: "session.reconnect.ready" }), + ); + expect(vi.getTimerCount()).toBe(0); + }); + + it("ignores late events from a socket replaced by reconnect", async () => { + vi.useFakeTimers(); + const onAudio = vi.fn(); + const onClose = vi.fn(); + const onError = vi.fn(); + const bridge = createNativeBridge({ + onAudio, + onClose, + onError, + }); + const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); + + openSocket(firstSocket); + emitSessionUpdated(firstSocket); + await connecting; + + firstSocket.readyState = FakeWebSocket.CLOSED; + firstSocket.emit("close", 1006, Buffer.from("transient drop")); + firstSocket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + delta: Buffer.from("late audio").toString("base64"), + }), + ), + ); + firstSocket.emit("error", new Error("late retry-wait failure")); + expect(onAudio).not.toHaveBeenCalled(); + expect(onError).not.toHaveBeenCalled(); + + await vi.advanceTimersByTimeAsync(1000); + const secondSocket = requireSocket(1); + openSocket(secondSocket); + emitSessionUpdated(secondSocket); + await vi.waitFor(() => expect(bridge.isConnected()).toBe(true)); + + emitSessionUpdated(firstSocket); + firstSocket.emit("error", new Error("late socket failure")); + firstSocket.emit("close", 1006, Buffer.from("late socket close")); + await vi.advanceTimersByTimeAsync(0); + + expect(bridge.isConnected()).toBe(true); + expect(FakeWebSocket.instances).toHaveLength(2); + expect(vi.getTimerCount()).toBe(0); + expect(onError).not.toHaveBeenCalled(); + expect(onClose).not.toHaveBeenCalled(); + bridge.close(); + }); + + it("exhausts retries when sockets open but never become provider-ready", async () => { + vi.useFakeTimers(); + const onClose = vi.fn(); + const onError = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onClose, onError, onEvent }); + const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); + + openSocket(firstSocket); + emitSessionUpdated(firstSocket); + await connecting; + + firstSocket.readyState = FakeWebSocket.CLOSED; + firstSocket.emit("close", 1006, Buffer.from("transient drop")); + + for (let attempt = 1; attempt <= 5; attempt += 1) { + await vi.waitFor(() => + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "session.reconnect.scheduled", + detail: `reason=websocket-close attempt=${attempt} delayMs=${1000 * 2 ** (attempt - 1)}`, + }), + ); + await vi.advanceTimersByTimeAsync(1000 * 2 ** (attempt - 1)); + const retrySocket = requireSocket(attempt); + openSocket(retrySocket); + retrySocket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { message: `retry startup failure ${attempt}` }, + }), + ), + ); + } + + await vi.waitFor(() => expect(onClose).toHaveBeenCalledWith("error")); + expect(onClose).toHaveBeenCalledOnce(); + expect(onError).toHaveBeenCalledTimes(5); + expect(FakeWebSocket.instances).toHaveLength(6); + expect(onEvent).toHaveBeenCalledWith({ + direction: "client", + type: "session.reconnect.exhausted", + detail: "reason=websocket-close attempts=5", + }); + + bridge.close(); + expect(onClose).toHaveBeenCalledOnce(); + }); + + it("keeps a retried connection ready after delayed startup failure close", async () => { + const onClose = vi.fn(); + const bridge = createNativeBridge({ onClose }); + const { connecting: failedConnect, socket: failedSocket } = beginBridgeConnection(bridge); + failedSocket.deferClose = true; + + openSocket(failedSocket); + failedSocket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { message: "Incorrect API key provided" }, + }), + ), + ); + + await expect(failedConnect).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); + expect(failedSocket.deferredClose).toBeDefined(); + + const { connecting: retryConnect, socket: retrySocket } = beginBridgeConnection(bridge, 1); + openSocket(retrySocket); + emitSessionUpdated(retrySocket); + await retryConnect; + + expect(bridge.isConnected()).toBe(true); + failedSocket.emitDeferredClose(); + expect(bridge.isConnected()).toBe(true); + expect(onClose).not.toHaveBeenCalled(); + }); + + it("resets consumer tool ownership before a fresh reconnect can reuse a call id", async () => { + vi.useFakeTimers(); + const staleWork = new AbortController(); + const onEvent = vi.fn((event: RealtimeVoiceBridgeEvent) => { + if (event.direction === "client" && event.type === "session.continuity.reset") { + staleWork.abort(); + } + }); + const onToolCall = vi.fn(); + const bridge = createNativeBridge({ onEvent, onToolCall }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket, ["call_reused"]); + expect(onToolCall).toHaveBeenCalledTimes(1); + + socket.emit("close", 1006, Buffer.from("transient drop")); + const lifecycleEvents = onEvent.mock.calls.map(([event]) => event.type); + expect(lifecycleEvents.indexOf("session.continuity.reset")).toBeLessThan( + lifecycleEvents.indexOf("session.reconnect.scheduled"), + ); + await vi.advanceTimersByTimeAsync(1000); + const reconnectedSocket = requireSocket(1); + openSocket(reconnectedSocket); + emitSessionUpdated(reconnectedSocket); + + emitCompletedToolCalls(socket, ["call_from_old_socket"]); + expect( + parseSent(reconnectedSocket).filter((event) => event.type === "conversation.item.create"), + ).toEqual([]); + expect(onToolCall).toHaveBeenCalledTimes(1); + + emitCompletedToolCalls(reconnectedSocket, ["call_reused"]); + if (!staleWork.signal.aborted) { + void bridge.submitToolResult("call_reused", { text: "stale" }); + } + const fresh = bridge.submitToolResult("call_reused", { text: "fresh" }); + emitFunctionOutputAdded(reconnectedSocket, "call_reused"); + await fresh; + + expect(onToolCall).toHaveBeenCalledTimes(2); + expect( + parseSent(reconnectedSocket) + .filter( + (event) => + event.type === "conversation.item.create" && + (event.item as { call_id?: string } | undefined)?.call_id === "call_reused", + ) + .map((event) => (event.item as { output?: string } | undefined)?.output), + ).toEqual([JSON.stringify({ text: "fresh" })]); + }); +}); diff --git a/extensions/openai/realtime-voice-bridge-tools.test.ts b/extensions/openai/realtime-voice-bridge-tools.test.ts new file mode 100644 index 000000000000..12cc220588bc --- /dev/null +++ b/extensions/openai/realtime-voice-bridge-tools.test.ts @@ -0,0 +1,697 @@ +// Openai tests cover realtime voice provider plugin behavior. +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + parseSent, + createNativeBridge, + emitServerEvent, + emitCompletedToolCalls, + emitFunctionOutputAdded, + expectedFunctionOutput, + connectReadyBridge, + expectedResponseCreateEvent, + hasSentEventType, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice bridge tools", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("executes tool calls only from successful response output", async () => { + const onToolCall = vi.fn(); + const bridge = createNativeBridge({ onToolCall }); + const socket = await connectReadyBridge(bridge); + + emitServerEvent(socket, { + type: "response.function_call_arguments.delta", + item_id: "item_tool_1", + name: "openclaw_agent_consult", + call_id: "call_1", + delta: '{"question":"provisional', + }); + emitServerEvent(socket, { + type: "response.function_call_arguments.done", + item_id: "item_tool_1", + name: "openclaw_agent_consult", + call_id: "call_1", + arguments: '{"question":"still provisional"}', + }); + emitServerEvent(socket, { + type: "conversation.item.done", + item: { + id: "item_tool_1", + type: "function_call", + name: "openclaw_agent_consult", + call_id: "call_1", + arguments: '{"question":"not terminal"}', + }, + }); + expect(onToolCall).not.toHaveBeenCalled(); + + const completed = { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: [ + { + id: "item_tool_1", + type: "function_call", + status: "completed", + name: "openclaw_agent_consult", + call_id: "call_1", + arguments: '{"question":"delegate this"}', + }, + ], + }, + }; + emitServerEvent(socket, completed); + emitServerEvent(socket, completed); + + expect(onToolCall).toHaveBeenCalledTimes(1); + expect(onToolCall).toHaveBeenCalledWith({ + itemId: "item_tool_1", + callId: "call_1", + name: "openclaw_agent_consult", + args: { question: "delegate this" }, + }); + }); + + it.each(["cancelled", "failed", "incomplete"])( + "ignores function calls from a %s response", + async (status) => { + const onToolCall = vi.fn(); + const bridge = createNativeBridge({ onToolCall }); + const socket = await connectReadyBridge(bridge); + + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_1", + status, + output: [ + { + id: "item_tool_1", + type: "function_call", + status: "completed", + name: "openclaw_agent_consult", + call_id: "call_1", + arguments: '{"question":"must stay inert"}', + }, + ], + }, + }); + + expect(onToolCall).not.toHaveBeenCalled(); + }, + ); + + it("ignores malformed and unfinished response output items", async () => { + const onToolCall = vi.fn(); + const bridge = createNativeBridge({ onToolCall }); + const socket = await connectReadyBridge(bridge); + + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: [ + null, + "invalid", + { + id: "item_tool_1", + type: "function_call", + status: "incomplete", + name: "openclaw_agent_consult", + call_id: "call_1", + arguments: '{"question":"unfinished"}', + }, + ], + }, + }); + + expect(onToolCall).not.toHaveBeenCalled(); + }); + + it.each([ + { + name: "an argument object", + finalArguments: '{"city":"Paris"}', + expectedArguments: { city: "Paris" }, + }, + { + name: "the shipped empty argument contract", + finalArguments: "", + expectedArguments: {}, + }, + ])( + "uses terminal response arguments for $name", + async ({ finalArguments, expectedArguments }) => { + const onToolCall = vi.fn(); + const bridge = createNativeBridge({ onToolCall }); + const socket = await connectReadyBridge(bridge); + + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: [ + { + id: "item_tool_1", + type: "function_call", + status: "completed", + call_id: "call_1", + name: "lookup_weather", + arguments: finalArguments, + }, + ], + }, + }); + + expect(onToolCall).toHaveBeenCalledWith({ + itemId: "item_tool_1", + callId: "call_1", + name: "lookup_weather", + args: expectedArguments, + }); + }, + ); + + it.each([ + { name: "malformed JSON", arguments: '{"city":', reason: "malformed-json" }, + { name: "an array", arguments: '["Paris"]', reason: "non-object-json" }, + { name: "JSON null", arguments: "null", reason: "non-object-json" }, + { name: "a number", arguments: "42", reason: "non-object-json" }, + { name: "a boolean", arguments: "true", reason: "non-object-json" }, + { name: "missing arguments", arguments: undefined, reason: "invalid-json-type" }, + { name: "non-string arguments", arguments: { city: "Paris" }, reason: "invalid-json-type" }, + ])("rejects $name per call without ending the session", async ({ arguments: args, reason }) => { + const onToolCall = vi.fn(); + const onError = vi.fn(); + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onToolCall, onError, onEvent }); + const socket = await connectReadyBridge(bridge); + const completed = { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: [ + { + id: "item_tool_1", + type: "function_call", + status: "completed", + call_id: "call_1", + name: "lookup_weather", + arguments: args, + }, + ], + }, + }; + + emitServerEvent(socket, { type: "response.created", response: { id: "response_1" } }); + emitServerEvent(socket, completed); + emitServerEvent(socket, completed); + + expect(onToolCall).not.toHaveBeenCalled(); + expect(onError).not.toHaveBeenCalled(); + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "tool_call.arguments.rejected", + detail: `reason=${reason}`, + itemId: "item_tool_1", + }); + expect( + parseSent(socket).filter( + (event) => + event.type === "conversation.item.create" && + (event.item as { call_id?: string } | undefined)?.call_id === "call_1", + ), + ).toHaveLength(1); + }); + + it.each([ + { + name: "accepts", + encoding: "ASCII", + argumentBytes: 256_000, + unit: "a", + repeat: 255_992, + suffix: "", + rejected: false, + }, + { + name: "rejects", + encoding: "ASCII", + argumentBytes: 256_001, + unit: "a", + repeat: 255_993, + suffix: "", + rejected: true, + }, + { + name: "accepts", + encoding: "multibyte", + argumentBytes: 256_000, + unit: "é", + repeat: 127_996, + suffix: "", + rejected: false, + }, + { + name: "rejects", + encoding: "multibyte", + argumentBytes: 256_001, + unit: "é", + repeat: 127_996, + suffix: "a", + rejected: true, + }, + ])( + "$name $argumentBytes-byte $encoding UTF-8 arguments", + async ({ argumentBytes, unit, repeat, suffix, rejected }) => { + const onToolCall = vi.fn(); + const onError = vi.fn(); + const bridge = createNativeBridge({ onToolCall, onError }); + const socket = await connectReadyBridge(bridge); + const rawArgs = `{"x":"${unit.repeat(repeat)}${suffix}"}`; + expect(Buffer.byteLength(rawArgs, "utf8")).toBe(argumentBytes); + + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: [ + { + id: "item_tool_1", + type: "function_call", + status: "completed", + call_id: "call_1", + name: "lookup_weather", + arguments: rawArgs, + }, + ], + }, + }); + + expect(onToolCall).toHaveBeenCalledTimes(rejected ? 0 : 1); + expect( + parseSent(socket).some( + (event) => + event.type === "conversation.item.create" && + (event.item as { call_id?: string } | undefined)?.call_id === "call_1", + ), + ).toBe(rejected); + expect(onError).not.toHaveBeenCalled(); + }, + ); + + it("ends an extreme session before terminal tool-call ids become unbounded", async () => { + const onToolCall = vi.fn(); + const onError = vi.fn(); + const onClose = vi.fn(); + const bridge = createNativeBridge({ onToolCall, onError, onClose }); + const socket = await connectReadyBridge(bridge); + + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: Array.from({ length: 1_025 }, (_, index) => ({ + id: `item_${index}`, + type: "function_call", + status: "completed", + call_id: `call_${index}`, + name: "lookup_weather", + arguments: "{}", + })), + }, + }); + + expect(onToolCall).toHaveBeenCalledTimes(1_024); + expect(onError).toHaveBeenCalledOnce(); + expect(onError).toHaveBeenCalledWith( + new Error("OpenAI realtime tool-call session limit exceeded (1024)"), + ); + expect(onClose).toHaveBeenCalledWith("error"); + expect(socket.closed).toBe(true); + await expect(bridge.connect()).rejects.toThrow( + "OpenAI realtime tool-call session limit exceeded (1024)", + ); + }); + + it("stops dispatching terminal output when a tool callback closes the bridge", async () => { + const onToolCall = vi.fn(); + const bridge = createNativeBridge({ onToolCall }); + onToolCall.mockImplementation(() => bridge.close()); + const socket = await connectReadyBridge(bridge); + + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_1", + status: "completed", + output: Array.from({ length: 2 }, (_, index) => ({ + id: `item_${index}`, + type: "function_call", + status: "completed", + call_id: `call_${index}`, + name: "lookup_weather", + arguments: "{}", + })), + }, + }); + + expect(onToolCall).toHaveBeenCalledTimes(1); + }); + + it.each([ + ["undefined", (): undefined => undefined], + ["function", () => () => undefined], + ["symbol", () => Symbol("invalid-tool-result")], + ["bigint", () => ({ value: 1n })], + [ + "circular", + () => { + const result: { self?: unknown } = {}; + result.self = result; + return result; + }, + ], + ["omitted custom serialization", () => ({ toJSON: () => undefined })], + ] as const)( + "rejects %s tool results without consuming a retryable call", + async (_label, create) => { + const bridge = createNativeBridge({ onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket); + const previousEventCount = socket.sent.length; + + expect(() => bridge.submitToolResult("call_1", create())).toThrow(); + expect(socket.sent).toHaveLength(previousEventCount); + expect(hasSentEventType(socket, "response.create")).toBe(false); + + await bridge.submitToolResult("call_1", { recovered: true }); + + expect(parseSent(socket).find((event) => event.type === "conversation.item.create")).toEqual({ + type: "conversation.item.create", + item: { + type: "function_call_output", + call_id: "call_1", + output: JSON.stringify({ recovered: true }), + }, + }); + }, + ); + + it("preserves valid JSON tool results and invokes custom serialization once", async () => { + const bridge = createNativeBridge({ onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + const values: unknown[] = [null, false, 0, "", "text", [1], { ok: true }]; + const customSerialization = vi.fn((key: string) => ({ key })); + values.push({ toJSON: customSerialization }); + const callIds = values.map((_, index) => `call_${index}`); + emitCompletedToolCalls(socket, callIds); + + for (const [index, result] of values.entries()) { + await bridge.submitToolResult(callIds[index]!, result, { suppressResponse: true }); + } + + const outputs = parseSent(socket) + .filter((event) => event.type === "conversation.item.create") + .map((event) => (event.item as { output: string }).output); + expect(outputs).toEqual([ + "null", + "false", + "0", + '""', + '"text"', + "[1]", + '{"ok":true}', + '{"key":""}', + ]); + expect(customSerialization).toHaveBeenCalledExactlyOnceWith(""); + }); + + it("does not request a realtime response for continuing tool results", async () => { + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onEvent, onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket); + + const working = bridge.submitToolResult( + "call_1", + { status: "working" }, + { willContinue: true }, + ); + + expect(parseSent(socket).slice(-1)).toEqual([ + expectedFunctionOutput("call_1", { status: "working" }), + ]); + expect(hasSentEventType(socket, "response.create")).toBe(false); + expect(working).toBeUndefined(); + + const done = bridge.submitToolResult("call_1", { text: "done" }); + expect(done).toBeUndefined(); + + expect(parseSent(socket).slice(-3)).toEqual([ + expectedFunctionOutput("call_1", { text: "done" }), + expect.objectContaining({ type: "session.update" }), + expectedResponseCreateEvent(), + ]); + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); + emitFunctionOutputAdded(socket, "call_1"); + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "conversation.item.added", + detail: "itemType=function_call_output", + }); + emitServerEvent(socket, { + type: "conversation.item.done", + item: { type: "function_call_output", call_id: "call_1" }, + }); + expect(onEvent).toHaveBeenCalledWith({ + direction: "server", + type: "conversation.item.done", + detail: "itemType=function_call_output", + }); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_2" } })), + ); + emitServerEvent(socket, { type: "response.done" }); + + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); + }); + + it("does not request a realtime response for suppressed tool results", async () => { + const bridge = createNativeBridge({ onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket); + + const submission = bridge.submitToolResult( + "call_1", + { status: "already_delivered" }, + { suppressResponse: true }, + ); + + expect(parseSent(socket).slice(-1)).toEqual([ + expectedFunctionOutput("call_1", { status: "already_delivered" }), + ]); + emitFunctionOutputAdded(socket, "call_1"); + await submission; + expect(hasSentEventType(socket, "response.create")).toBe(false); + }); + + it("waits for every parallel tool result before continuing the response", async () => { + const bridge = createNativeBridge({ onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket, ["call_1", "call_2"]); + + const first = bridge.submitToolResult("call_1", { text: "first" }); + emitFunctionOutputAdded(socket, "call_1"); + await first; + + expect(parseSent(socket).filter((event) => event.type === "response.create")).toEqual([]); + + const second = bridge.submitToolResult("call_2", { text: "second" }); + emitFunctionOutputAdded(socket, "call_2"); + await second; + + expect( + parseSent(socket).filter((event) => event.type === "conversation.item.create"), + ).toHaveLength(2); + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); + }); + + it("releases a deferred continuation when the last parallel result is suppressed", async () => { + const bridge = createNativeBridge({ onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket, ["call_1", "call_2"]); + + const first = bridge.submitToolResult("call_1", { text: "first" }); + const second = bridge.submitToolResult( + "call_2", + { status: "already_delivered" }, + { suppressResponse: true }, + ); + emitFunctionOutputAdded(socket, "call_1"); + emitFunctionOutputAdded(socket, "call_2"); + await Promise.all([first, second]); + + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); + }); + + it("does not flush deferred response.create while a tool result is still continuing", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError, onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + + emitCompletedToolCalls(socket); + const working = bridge.submitToolResult( + "call_1", + { status: "working" }, + { willContinue: true }, + ); + emitFunctionOutputAdded(socket, "call_1"); + await working; + bridge.sendUserMessage?.("queue after tool result"); + + expect(onError).not.toHaveBeenCalled(); + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_status" } })), + ); + emitServerEvent(socket, { + type: "response.done", + response: { id: "resp_status", status: "completed", output: [] }, + }); + + const done = bridge.submitToolResult("call_1", { text: "done" }); + emitFunctionOutputAdded(socket, "call_1"); + await done; + + expect(parseSent(socket).slice(-3)).toEqual([ + expectedFunctionOutput("call_1", { text: "done" }), + expect.objectContaining({ type: "session.update" }), + expectedResponseCreateEvent(), + ]); + }); +}); diff --git a/extensions/openai/realtime-voice-bridge.ts b/extensions/openai/realtime-voice-bridge.ts new file mode 100644 index 000000000000..fbcee5b08044 --- /dev/null +++ b/extensions/openai/realtime-voice-bridge.ts @@ -0,0 +1,700 @@ +import { randomUUID } from "node:crypto"; +import { toStringifiedError } from "openclaw/plugin-sdk/error-runtime"; +import { resolveProviderRequestHeaders } from "openclaw/plugin-sdk/provider-http"; +import { + captureWsEvent, + createDebugProxyWebSocketAgent, + resolveDebugProxySettings, +} from "openclaw/plugin-sdk/proxy-capture"; +import type { + RealtimeVoiceBridge, + RealtimeVoiceSessionConnection, + RealtimeVoiceToolResultOptions, +} from "openclaw/plugin-sdk/realtime-voice"; +import { RealtimeVoiceSessionLifecycle } from "openclaw/plugin-sdk/realtime-voice"; +import { sleepWithAbort } from "openclaw/plugin-sdk/runtime-env"; +import WebSocket from "ws"; +import { + captureOpenAIRealtimeWsClose, + readRealtimeErrorDetail, +} from "./realtime-provider-shared.js"; +import { buildOpenAIRealtimeSidebandUrl } from "./realtime-quicksilver-wire.js"; +import { + OpenAIRealtimeEvents, + OpenAIRealtimeMalformedAudioError, +} from "./realtime-voice-events.js"; +import { + OPENAI_REALTIME_DEFAULT_MODEL, + OPENAI_REALTIME_API_KEY_REQUIRED, + OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED, + OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED, + OPENAI_REALTIME_SIDEBAND_STARTUP_MAX_BYTES, + OPENAI_VOICE_WS_MAX_PAYLOAD_BYTES, + hasOpenAIRealtimeConfiguredApiKeyInput, + isDirectOpenAIRealtimeWebSocketUrl, + isOpenAIRealtimeStartupAuthFailure, + requireOpenAIRealtimeApiKey, + requireOpenAIRealtimePlatformAuth, + resolveOpenAIRealtimeEnvApiKey, + resolveOpenAIRealtimeSecretInput, + type OpenAIRealtimeUserMessageOptions, + type RealtimeEvent, +} from "./realtime-voice-session-policy.js"; + +export class OpenAIRealtimeBridge extends OpenAIRealtimeEvents implements RealtimeVoiceBridge { + private static readonly DEFAULT_MODEL = OPENAI_REALTIME_DEFAULT_MODEL; + + private static readonly MAX_RECONNECT_ATTEMPTS = 5; + + private static readonly BASE_RECONNECT_DELAY_MS = 1000; + + private static readonly CONNECT_TIMEOUT_MS = 10_000; + + private ws: WebSocket | null = null; + + private readonly lifecycle = new RealtimeVoiceSessionLifecycle("OpenAI"); + + private connectionUrl = ""; + + private readonly flowId = randomUUID(); + + private sessionReadyFired = false; + + private reconnectReason: string | undefined; + + private activeConnectionReason: string | undefined; + + private terminalError: Error | undefined; + + async connect(): Promise { + if (this.terminalError) { + throw this.terminalError; + } + await this.lifecycle.connect((connection) => this.doConnect(connection)); + } + + sendAudio(audio: Buffer): void { + if (this.lifecycle.phase() === "terminal") { + return; + } + if (!this.lifecycle.isReady() || this.ws?.readyState !== WebSocket.OPEN) { + this.lifecycle.enqueuePendingAudio(audio); + return; + } + this.sendEvent({ + type: "input_audio_buffer.append", + audio: audio.toString("base64"), + }); + } + + sendUserMessage(text: string, options?: OpenAIRealtimeUserMessageOptions): void { + if ( + options?.toolChoice && + (this.responseActive || + this.responseCreateInFlight || + this.responseCancelInFlight || + this.pendingToolCallIds.size > 0) + ) { + throw new Error("Forced realtime tool choice requires an idle response state"); + } + if (this.pendingToolCallIds.size > 0) { + // Control/status speech must not wait behind the long-running consult whose + // function output owns the default conversation response. + this.standaloneSpeechQueue.push(text); + this.flushStandaloneSpeech(); + return; + } + this.sendEvent({ + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [{ type: "input_text", text }], + }, + }); + this.requestResponseCreate(options); + } + + triggerGreeting(instructions?: string): void { + if (!this.isConnected() || !this.ws) { + return; + } + this.sendUserMessage(instructions ?? this.config.instructions ?? "Greet the meeting."); + } + + submitToolResult( + callId: string, + result: unknown, + options?: RealtimeVoiceToolResultOptions, + ): void { + if (this.lifecycle.phase() === "terminal" || !this.pendingToolCallIds.has(callId)) { + return; + } + const output = JSON.stringify(result); + if (typeof output !== "string") { + throw new Error("OpenAI realtime voice tool result is not JSON-serializable"); + } + this.sendEvent({ + type: "conversation.item.create", + item: { + type: "function_call_output", + call_id: callId, + output, + }, + }); + if (options?.willContinue === true) { + this.continuingToolCallIds.add(callId); + return; + } + this.continuingToolCallIds.delete(callId); + this.pendingToolCallIds.delete(callId); + if (options?.suppressResponse === true) { + this.flushPendingResponseCreate(); + return; + } + this.requestResponseCreate(); + } + + close(): void { + const connection = this.lifecycle.currentConnection(); + if (!this.lifecycle.cancel()) { + return; + } + this.resetTerminalState(); + if (!connection) { + return; + } + const ws = this.ws; + this.ws = null; + ws?.close(1000, "Bridge closed"); + this.notifyClose(connection, "completed"); + } + + isConnected(): boolean { + return this.lifecycle.isReady() && this.ws?.readyState === WebSocket.OPEN; + } + + private async doConnect(lifecycleConnection: RealtimeVoiceSessionConnection): Promise { + let activeWs: WebSocket | undefined; + let startupFrameBytes = 0; + const attempt = this.lifecycle.createConnectAttempt({ + connection: lifecycleConnection, + timeoutMs: OpenAIRealtimeBridge.CONNECT_TIMEOUT_MS, + timeoutError: () => new Error("OpenAI realtime connection timeout"), + onTimeout: () => activeWs?.terminate(), + onAbort: () => { + if (activeWs && activeWs.readyState !== WebSocket.CLOSED) { + activeWs.close(1000, "connection canceled"); + } + }, + }); + + const openWebSocket = (resolvedConnection: { + url: string; + headers: Record; + }) => { + if (attempt.settled) { + return; + } + if (!this.lifecycle.isCurrent(lifecycleConnection) || lifecycleConnection.signal.aborted) { + attempt.resolve(); + return; + } + // Auth preparation owns its own timeout. Start the socket deadline only + // after connection parameters are available. + attempt.startTimeout(); + const url = resolvedConnection.url; + this.connectionUrl = resolvedConnection.url; + const debugProxy = resolveDebugProxySettings(); + const proxyAgent = createDebugProxyWebSocketAgent(debugProxy); + const ws = new WebSocket(resolvedConnection.url, { + headers: resolvedConnection.headers, + maxPayload: OPENAI_VOICE_WS_MAX_PAYLOAD_BYTES, + ...(proxyAgent ? { agent: proxyAgent } : {}), + }); + activeWs = ws; + this.ws = ws; + + const rejectStartup = (error: Error) => { + if (!attempt.rejectStartup(error)) { + return; + } + if (ws.readyState !== WebSocket.CLOSED) { + ws.close(1000, "startup failed"); + } + }; + + ws.on("open", () => { + if (!this.lifecycle.acceptsEvents(lifecycleConnection)) { + ws.close(1000, "stale connection"); + return; + } + this.resetRealtimeSessionState(); + captureWsEvent({ + url, + direction: "local", + kind: "ws-open", + flowId: this.flowId, + meta: { + provider: "openai", + capability: "realtime-voice", + }, + }); + this.sendSessionUpdate(); + }); + + ws.on("message", (data: Buffer) => { + if (!this.lifecycle.acceptsEvents(lifecycleConnection) || this.ws !== ws) { + return; + } + if (attempt.settled && !attempt.ready) { + return; + } + if (!attempt.ready) { + startupFrameBytes += data.byteLength; + if (startupFrameBytes > OPENAI_REALTIME_SIDEBAND_STARTUP_MAX_BYTES) { + const error = new Error("OpenAI realtime sideband startup buffer exceeded"); + attempt.reject(error); + this.failConnection(error, ws, lifecycleConnection, { + code: 1009, + reason: "Sideband startup buffer exceeded", + }); + return; + } + } + captureWsEvent({ + url, + direction: "inbound", + kind: "ws-frame", + flowId: this.flowId, + payload: data, + meta: { + provider: "openai", + capability: "realtime-voice", + }, + }); + try { + const event = JSON.parse(data.toString()) as RealtimeEvent; + if (event.type === "error" && !attempt.ready) { + // Only direct OpenAI auth failures get bounded remediation. Azure, + // custom endpoints, and non-auth startup details remain provider-owned. + rejectStartup( + isDirectOpenAIRealtimeWebSocketUrl(url) && + isOpenAIRealtimeStartupAuthFailure(event.error) + ? new Error(OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED) + : new Error(readRealtimeErrorDetail(event.error)), + ); + return; + } + if (event.type === "session.updated") { + try { + this.handleEvent(event, lifecycleConnection); + } catch (error) { + const readyError = toStringifiedError(error); + attempt.reject(readyError); + this.failConnection(readyError, ws, lifecycleConnection, { + code: 1011, + reason: "Readiness callback failed", + }); + return; + } + attempt.resolve(this.lifecycle.isReady()); + return; + } + this.handleEvent(event, lifecycleConnection); + } catch (error) { + if (error instanceof OpenAIRealtimeMalformedAudioError) { + attempt.reject(error); + this.failConnection(error, ws, lifecycleConnection, { + code: 1002, + reason: "Malformed audio payload", + }); + return; + } + console.error("[openai] realtime event parse failed:", error); + } + }); + + ws.on("error", (error) => { + if (!this.lifecycle.acceptsEvents(lifecycleConnection) || this.ws !== ws) { + return; + } + captureWsEvent({ + url, + direction: "local", + kind: "error", + flowId: this.flowId, + errorText: error instanceof Error ? error.message : String(error), + meta: { + provider: "openai", + capability: "realtime-voice", + }, + }); + if (!attempt.ready) { + const startupError = toStringifiedError(error); + rejectStartup( + isDirectOpenAIRealtimeWebSocketUrl(url) && + isOpenAIRealtimeStartupAuthFailure(startupError) + ? new Error(OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED) + : startupError, + ); + return; + } + this.config.onError?.(toStringifiedError(error)); + }); + + ws.on("close", (code, reasonBuffer) => { + captureOpenAIRealtimeWsClose({ + url, + flowId: this.flowId, + capability: "realtime-voice", + code, + reasonBuffer, + }); + if (!this.lifecycle.isCurrent(lifecycleConnection)) { + return; + } + if (this.ws === ws) { + this.ws = null; + } + if (attempt.startupFailed) { + return; + } + if (this.terminalError) { + this.notifyClose(lifecycleConnection, "error"); + return; + } + if (this.lifecycle.terminalOutcome(lifecycleConnection) === "completed") { + attempt.resolve(); + this.notifyClose(lifecycleConnection, "completed"); + return; + } + if (!attempt.ready && !attempt.settled) { + const error = new Error("OpenAI realtime connection closed before ready"); + attempt.reject(error); + return; + } + const reason = this.reconnectReason ?? "websocket-close"; + this.reconnectReason = undefined; + void this.attemptReconnect(reason, lifecycleConnection); + }); + }; + + let connectionOrPromise: + | { url: string; headers: Record } + | Promise<{ url: string; headers: Record }>; + try { + connectionOrPromise = this.resolveConnectionParams(); + } catch (error) { + attempt.reject(toStringifiedError(error)); + return attempt.promise; + } + if (connectionOrPromise instanceof Promise) { + void connectionOrPromise.then(openWebSocket).catch((error: unknown) => { + if ( + !this.lifecycle.isCurrent(lifecycleConnection) || + this.lifecycle.terminalOutcome(lifecycleConnection) === "completed" + ) { + attempt.resolve(); + return; + } + attempt.reject(toStringifiedError(error)); + }); + } else { + try { + openWebSocket(connectionOrPromise); + } catch (error) { + attempt.reject(toStringifiedError(error)); + } + } + await attempt.promise; + } + + private resolveConnectionParams(): + | { url: string; headers: Record } + | Promise<{ url: string; headers: Record }> { + const cfg = this.config; + const model = cfg.model ?? OpenAIRealtimeBridge.DEFAULT_MODEL; + if (cfg.azureEndpoint && cfg.azureDeployment) { + const apiKey = requireOpenAIRealtimeApiKey(cfg.apiKey); + const base = cfg.azureEndpoint + .replace(/\/$/, "") + .replace(/^http(s?):/, (_, secure: string) => `ws${secure}:`); + const apiVersion = cfg.azureApiVersion ?? "2024-10-01-preview"; + const url = `${base}/openai/realtime?api-version=${apiVersion}&deployment=${encodeURIComponent( + cfg.azureDeployment, + )}`; + return { + url, + headers: resolveProviderRequestHeaders({ + provider: "openai", + baseUrl: url, + capability: "audio", + transport: "websocket", + defaultHeaders: { "api-key": apiKey }, + }) ?? { "api-key": apiKey }, + }; + } + + if (hasOpenAIRealtimeConfiguredApiKeyInput(cfg.apiKey)) { + const directApiKey = resolveOpenAIRealtimeSecretInput(cfg.apiKey); + if (directApiKey.status === "missing") { + throw new Error(OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED); + } + return this.resolveApiKeyConnectionParams(directApiKey.value, model); + } + + if (cfg.azureEndpoint) { + const directApiKey = resolveOpenAIRealtimeEnvApiKey(); + if (directApiKey.status === "missing") { + throw new Error(OPENAI_REALTIME_API_KEY_REQUIRED); + } + return this.resolveApiKeyConnectionParams(directApiKey.value, model); + } + + return this.resolveDefaultConnectionParams(model); + } + + private async resolveDefaultConnectionParams(model: string): Promise<{ + url: string; + headers: Record; + }> { + const auth = await requireOpenAIRealtimePlatformAuth({ + configuredApiKey: this.config.apiKey, + cfg: this.config.cfg, + }); + return this.resolveApiKeyConnectionParams(auth.value, model); + } + + private resolveApiKeyConnectionParams( + apiKey: string, + model: string, + ): { url: string; headers: Record } { + const cfg = this.config; + if (cfg.azureEndpoint) { + const base = cfg.azureEndpoint + .replace(/\/$/, "") + .replace(/^http(s?):/, (_, secure: string) => `ws${secure}:`); + const url = `${base}/v1/realtime?model=${encodeURIComponent(model)}`; + return { + url, + headers: resolveProviderRequestHeaders({ + provider: "openai", + baseUrl: url, + capability: "audio", + transport: "websocket", + defaultHeaders: { Authorization: `Bearer ${apiKey}` }, + }) ?? { Authorization: `Bearer ${apiKey}` }, + }; + } + + const url = cfg.callId + ? buildOpenAIRealtimeSidebandUrl(cfg.callId) + : `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(model)}`; + return { + url, + headers: resolveProviderRequestHeaders({ + provider: "openai", + baseUrl: url, + capability: "audio", + transport: "websocket", + defaultHeaders: { + Authorization: `Bearer ${apiKey}`, + }, + }) ?? { + Authorization: `Bearer ${apiKey}`, + }, + }; + } + + private async attemptReconnect( + reason: string, + connection: RealtimeVoiceSessionConnection, + ): Promise { + const retry = this.lifecycle.retry(connection, OpenAIRealtimeBridge.MAX_RECONNECT_ATTEMPTS); + if (!retry) { + return; + } + if (retry === "exhausted") { + this.config.onEvent?.({ + direction: "client", + type: "session.reconnect.exhausted", + detail: `reason=${reason} attempts=${OpenAIRealtimeBridge.MAX_RECONNECT_ATTEMPTS}`, + }); + if (this.lifecycle.failure(connection)) { + this.resetTerminalState(); + } + this.notifyClose(connection, "error"); + return; + } + const attempt = retry.attempt; + const delay = OpenAIRealtimeBridge.BASE_RECONNECT_DELAY_MS * 2 ** (attempt - 1); + if (attempt === 1) { + // OpenAI reconnects start a fresh provider generation. Reset consumers + // before backoff so stale async work cannot satisfy reused call ids. + this.resetRealtimeSessionState(); + this.config.onEvent?.({ + direction: "client", + type: "session.continuity.reset", + }); + } + this.config.onEvent?.({ + direction: "client", + type: "session.reconnect.scheduled", + detail: `reason=${reason} attempt=${attempt} delayMs=${delay}`, + }); + try { + await sleepWithAbort(delay, retry.signal); + } catch (error) { + if (!retry.signal.aborted) { + throw error; + } + return; + } + const nextConnection = this.lifecycle.reconnect(connection); + if (!nextConnection) { + return; + } + try { + await this.doConnect(nextConnection); + if (!this.lifecycle.isCurrent(nextConnection) || !this.lifecycle.isReady()) { + return; + } + this.config.onEvent?.({ + direction: "client", + type: "session.reconnect.ready", + detail: `reason=${reason} attempt=${attempt}`, + }); + } catch (error) { + if (!this.lifecycle.acceptsEvents(nextConnection)) { + return; + } + this.config.onError?.(toStringifiedError(error)); + await this.attemptReconnect(reason, nextConnection); + } + } + + private markSessionReady(connection: RealtimeVoiceSessionConnection): void { + if (!this.lifecycle.ready(connection)) { + return; + } + if (this.activeConnectionReason) { + this.config.onEvent?.({ + direction: "server", + type: "session.rotation.ready", + detail: `reason=${this.activeConnectionReason}`, + }); + this.activeConnectionReason = undefined; + } + if (!this.sessionReadyFired) { + this.sessionReadyFired = true; + this.config.onReady?.(); + } + for (const chunk of this.lifecycle.drainPendingAudio()) { + this.sendAudio(chunk); + } + } + + private resetTerminalState(): void { + // Transport retries preserve readiness and rotation attribution. A terminal + // session clears both so explicit bridge reuse starts as a new session. + this.sessionReadyFired = false; + this.reconnectReason = undefined; + this.activeConnectionReason = undefined; + this.resetRealtimeSessionState(); + } + + private failConnection( + error: Error, + ws: WebSocket, + connection: RealtimeVoiceSessionConnection, + close: { code: number; reason: string }, + ): void { + if (this.terminalError) { + return; + } + this.terminalError = error; + this.lifecycle.failure(connection); + this.resetTerminalState(); + try { + this.config.onError?.(error); + } finally { + if (ws.readyState !== WebSocket.CLOSED) { + ws.close(close.code, close.reason); + } else { + this.notifyClose(connection, "error"); + } + } + } + + private notifyClose( + connection: RealtimeVoiceSessionConnection, + outcome: "completed" | "error", + ): void { + const terminalOutcome = this.lifecycle.close(connection, outcome); + if (!terminalOutcome) { + return; + } + this.resetTerminalState(); + this.config.onClose?.(terminalOutcome); + } + + protected sendEvent(event: unknown, detail?: string): void { + if (this.ws?.readyState === WebSocket.OPEN) { + const type = + event && typeof event === "object" && typeof (event as { type?: unknown }).type === "string" + ? (event as { type: string }).type + : "unknown"; + this.config.onEvent?.({ direction: "client", type, ...(detail ? { detail } : {}) }); + const payload = JSON.stringify(event); + captureWsEvent({ + url: this.connectionUrl, + direction: "outbound", + kind: "ws-frame", + flowId: this.flowId, + payload, + meta: { + provider: "openai", + capability: "realtime-voice", + }, + }); + this.ws.send(payload); + } + } + + protected acceptsEvent(connection: RealtimeVoiceSessionConnection): boolean { + return this.lifecycle.acceptsEvents(connection); + } + + protected isTransportOpen(): boolean { + return this.ws?.readyState === WebSocket.OPEN; + } + + protected onSessionUpdated(connection: RealtimeVoiceSessionConnection): void { + this.markSessionReady(connection); + } + + protected rotateExpiredSession(): void { + this.reconnectReason = "max-duration"; + this.activeConnectionReason = "max-duration"; + this.config.onEvent?.({ + direction: "server", + type: "session.rotation", + detail: "reason=max-duration", + }); + this.ws?.close(1000, "max-duration rotation"); + } + + protected failToolCallSessionLimit( + error: Error, + connection: RealtimeVoiceSessionConnection, + ): void { + const ws = this.ws; + if (ws) { + this.failConnection(error, ws, connection, { + code: 1008, + reason: "Tool-call session limit exceeded", + }); + } + } +} diff --git a/extensions/openai/realtime-voice-browser-auth.test.ts b/extensions/openai/realtime-voice-browser-auth.test.ts new file mode 100644 index 000000000000..7f37fb805a69 --- /dev/null +++ b/extensions/openai/realtime-voice-browser-auth.test.ts @@ -0,0 +1,762 @@ +// Openai tests cover realtime voice provider plugin behavior. +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { buildOpenAIRealtimeVoiceProvider } from "./realtime-voice-provider.js"; + +const OPENAI_REALTIME_REJECTED_KEY_MESSAGE = + "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source"; + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + createNativeBridge, + beginBridgeConnection, + openSocket, + createJsonResponse, + requireRecord, + requireNestedRecord, + expectRecordFields, + firstMockCall, + requireFetchRequest, + requireFetchInit, + requireFetchHeaders, + requireFetchJsonBody, + createTestJwt, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice browser authentication", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("requires Platform auth for native realtime websocket bridges", async () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { model: "gpt-realtime-2" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + await expect(bridge.connect()).rejects.toThrow( + "OpenAI Realtime voice requires an OpenAI Platform API key", + ); + + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + expect(FakeWebSocket.instances).toHaveLength(0); + }); + + it("uses OPENAI_API_KEY for default GPT realtime bridges", async () => { + vi.stubEnv("OPENAI_API_KEY", "test-api-key-env"); + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { model: "gpt-realtime-2" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + void bridge.connect(); + await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(1)); + bridge.close(); + + expect(resolveProviderAuthProfileApiKeyMock.mock.calls).toEqual([ + [ + { + provider: "openai", + cfg: {}, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }, + ], + ]); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + const socket = FakeWebSocket.instances[0]; + const options = socket?.args[1] as { headers?: Record } | undefined; + expect(options?.headers?.Authorization).toBe("Bearer test-api-key-env"); + }); + + it("does not use Codex OAuth profiles for default GPT realtime bridges", async () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { model: "gpt-realtime-2" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + await expect(bridge.connect()).rejects.toThrow( + "OpenAI Realtime voice requires an OpenAI Platform API key", + ); + + expect(resolveProviderAuthProfileApiKeyMock.mock.calls).toEqual([ + [ + { + provider: "openai", + cfg: {}, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }, + ], + ]); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + expect(FakeWebSocket.instances).toHaveLength(0); + }); + + it("uses OPENAI_API_KEY when a configured API-key profile cannot be resolved", async () => { + vi.stubEnv("OPENAI_API_KEY", "test-api-key-env"); + resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined); + isProviderAuthProfileConfiguredMock.mockReturnValueOnce(true); + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { model: "gpt-realtime-2" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + void bridge.connect(); + await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(1)); + bridge.close(); + + expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledTimes(1); + const socket = FakeWebSocket.instances[0]; + const options = socket?.args[1] as { headers?: Record } | undefined; + expect(options?.headers?.Authorization).toBe("Bearer test-api-key-env"); + }); + + it("uses OpenAI API-key auth profiles", async () => { + resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce("test-api-key-profile"); + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { model: "gpt-realtime-2" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + void bridge.connect(); + await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(1)); + bridge.close(); + + expect(resolveProviderAuthProfileApiKeyMock.mock.calls).toEqual([ + [ + { + provider: "openai", + cfg: {}, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }, + ], + ]); + const socket = FakeWebSocket.instances[0]; + const options = socket?.args[1] as { headers?: Record } | undefined; + expect(options?.headers?.Authorization).toBe("Bearer test-api-key-profile"); + }); + + it("keeps explicit OpenAI realtime API keys as the advanced override", () => { + vi.stubEnv("OPENAI_API_KEY", "test-api-key-env"); + resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce("test-api-key-profile"); + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { + apiKey: "test-api-key-configured", + model: "gpt-realtime-2", + }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + void bridge.connect(); + bridge.close(); + + expect(resolveProviderAuthProfileApiKeyMock).not.toHaveBeenCalled(); + const socket = FakeWebSocket.instances[0]; + const options = socket?.args[1] as { headers?: Record } | undefined; + expect(options?.headers?.Authorization).toBe("Bearer test-api-key-configured"); + }); + + it("requires an API key for custom realtime endpoints", async () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: { + azureEndpoint: "https://example.openai.azure.com", + model: "gpt-realtime-2", + }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + await expect(bridge.connect()).rejects.toThrow("OpenAI Realtime voice requires an API key"); + + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + expect(FakeWebSocket.instances).toHaveLength(0); + }); + + it("returns browser-safe OpenClaw attribution headers for native WebRTC offers", async () => { + vi.stubEnv("OPENCLAW_VERSION", "2026.3.22"); + fetchWithSsrFGuardMock.mockResolvedValueOnce({ + response: createJsonResponse({ + client_secret: { value: "client-secret-123" }, + expires_at: 1_765_000_000, + }), + release: vi.fn(async () => undefined), + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + if (!provider.createBrowserSession) { + throw new Error("expected OpenAI realtime provider to support browser sessions"); + } + + const session = await provider.createBrowserSession({ + providerConfig: { apiKey: "test-api-key-test" }, + instructions: "Be concise.", + voice: " Marin ", + }); + + expectRecordFields(requireFetchRequest(), "fetch request", { + url: "https://api.openai.com/v1/realtime/client_secrets", + policy: { + allowRfc2544BenchmarkRange: true, + allowIpv6UniqueLocalRange: true, + hostnameAllowlist: ["api.openai.com"], + }, + }); + expectRecordFields(requireFetchInit(), "fetch init", { method: "POST" }); + expectRecordFields(requireFetchHeaders(), "fetch headers", { + Authorization: "Bearer test-api-key-test", + "Content-Type": "application/json", + originator: "openclaw", + version: "2026.3.22", + "User-Agent": "openclaw/2026.3.22", + }); + const body = requireFetchJsonBody(); + const bodySession = requireRecord(body.session, "fetch session"); + expect(bodySession.model).toBe("gpt-realtime-2.1"); + expect(requireNestedRecord(bodySession, ["audio", "input"])).toEqual({ + noise_reduction: { type: "near_field" }, + turn_detection: { + type: "server_vad", + create_response: true, + interrupt_response: true, + }, + transcription: { model: "gpt-4o-mini-transcribe" }, + }); + expect(requireNestedRecord(bodySession, ["audio", "output"])).toEqual({ voice: "marin" }); + expect(bodySession).not.toHaveProperty("temperature"); + expectRecordFields(session, "browser session", { + provider: "openai", + transport: "webrtc", + clientSecret: "client-secret-123", + offerUrl: "https://api.openai.com/v1/realtime/calls", + model: "gpt-realtime-2.1", + expiresAt: 1_765_000_000_000, + }); + // originator, version, and User-Agent are server-side attribution headers; they + // must not be forwarded to the browser so that the browser's direct SDP POST to + // api.openai.com passes the CORS preflight (only authorization,content-type + // allowed — #76435). All three are filtered, leaving no browser offer headers. + expect((session as { offerHeaders?: Record }).offerHeaders).toBeUndefined(); + }); + + it.each(["configured", "profile", "environment"] as const)( + "explains how auth precedence affects a rejected %s API key", + async (source) => { + if (source === "profile") { + resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce("test-api-key-profile"); + } else if (source === "environment") { + vi.stubEnv("OPENAI_API_KEY", "test-api-key-env"); + } + fetchWithSsrFGuardMock.mockResolvedValueOnce({ + response: createJsonResponse( + { error: { message: "Incorrect API key provided: test-api-key-proj-***" } }, + { status: 401 }, + ), + release: vi.fn(async () => undefined), + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + if (!provider.createBrowserSession) { + throw new Error("expected OpenAI realtime provider to support browser sessions"); + } + + await expect( + provider.createBrowserSession({ + providerConfig: source === "configured" ? { apiKey: "test-api-key-stale" } : {}, + }), + ).rejects.toThrow( + "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source", + ); + }, + ); + + it("resolves keychain OPENAI_API_KEY refs before creating browser sessions", async () => { + vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_BROWSER_TEST"); + execFileSyncMock.mockReturnValueOnce("test-api-key-browser-env\n"); + fetchWithSsrFGuardMock.mockResolvedValueOnce({ + response: createJsonResponse({ + client_secret: { value: "client-secret-123" }, + }), + release: vi.fn(async () => undefined), + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + if (!provider.createBrowserSession) { + throw new Error("expected OpenAI realtime provider to support browser sessions"); + } + + await provider.createBrowserSession({ + providerConfig: {}, + instructions: "Be concise.", + }); + + const [securityBinary, securityArgs, securityOptions] = firstMockCall( + execFileSyncMock, + "security keychain lookup", + ); + expect(securityBinary).toBe("/usr/bin/security"); + expect(securityArgs).toEqual([ + "find-generic-password", + "-s", + "openclaw", + "-a", + "OPENAI_REALTIME_BROWSER_TEST", + "-w", + ]); + expectRecordFields(securityOptions, "security command options", { + encoding: "utf8", + timeout: 5000, + }); + expectRecordFields(requireFetchHeaders(), "fetch headers", { + Authorization: "Bearer test-api-key-browser-env", + }); + }); + + it("resolves and caches keychain OPENAI_API_KEY refs before creating bridges", async () => { + vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_BRIDGE_TEST"); + execFileSyncMock.mockReturnValue("test-api-key-bridge-env\n"); + const provider = buildOpenAIRealtimeVoiceProvider(); + + const first = provider.createBridge({ + providerConfig: {}, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + const second = provider.createBridge({ + providerConfig: {}, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + void first.connect(); + void second.connect(); + await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(2)); + first.close(); + second.close(); + + expect(execFileSyncMock).toHaveBeenCalledTimes(1); + for (const socket of FakeWebSocket.instances) { + const options = socket.args[1] as { headers?: Record } | undefined; + expectRecordFields(options?.headers, "websocket headers", { + Authorization: "Bearer test-api-key-bridge-env", + }); + } + }); + + it("keeps Platform precedence for GA realtime when OAuth is also available", async () => { + const oauthToken = createTestJwt({ + "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, + }); + resolveProviderAuthProfileApiKeyMock.mockImplementation( + async ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") ? oauthToken : undefined, + ); + fetchWithSsrFGuardMock.mockResolvedValueOnce({ + response: createJsonResponse({ client_secret: { value: "client-secret-123" } }), + release: vi.fn(async () => undefined), + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + + await provider.createBrowserSession?.({ + providerConfig: { apiKey: "test-api-key-platform" }, + model: "gpt-realtime-2.1", + }); + + expect(resolveProviderAuthProfileApiKeyMock).not.toHaveBeenCalledWith( + expect.objectContaining({ profileTypes: ["oauth"] }), + ); + expectRecordFields(requireFetchHeaders(), "fetch headers", { + Authorization: "Bearer test-api-key-platform", + }); + }); + + it("does not use GA OAuth fallback when a Platform credential source is unresolved", async () => { + const oauthToken = createTestJwt({ + "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, + }); + resolveProviderAuthProfileApiKeyMock.mockImplementation( + async ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") ? oauthToken : undefined, + ); + isProviderAuthProfileConfiguredMock.mockImplementation( + ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("api_key") === true, + ); + const createBrowserSession = vi.fn(); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { handlesAgentConsult: true as const }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + + await expect( + provider.createBrowserSession?.({ + cfg: {} as never, + providerConfig: {}, + model: "gpt-realtime-2.1", + agentId: "main", + workspaceDir: "/tmp/openclaw-agent-workspace", + initialItems: [], + } as never), + ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); + expect(createBrowserSession).not.toHaveBeenCalled(); + expect(resolveProviderAuthProfileApiKeyMock).not.toHaveBeenCalledWith( + expect.objectContaining({ profileTypes: ["oauth"] }), + ); + }); + + it("requires Platform auth for browser sessions", async () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + await expect( + provider.createBrowserSession?.({ + providerConfig: {}, + }), + ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + }); + + it("reports an unresolved Platform credential without trying another auth route", async () => { + vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_MISSING_TEST"); + execFileSyncMock.mockImplementationOnce(() => { + throw new Error("keychain unavailable"); + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + + await expect( + provider.createBrowserSession?.({ + providerConfig: {}, + }), + ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); + }); + + it("treats OpenAI API-key auth profiles as configured for browser realtime sessions", () => { + isProviderAuthProfileConfiguredMock.mockReturnValue(true); + const provider = buildOpenAIRealtimeVoiceProvider(); + const cfg = { agents: { defaults: {} } } as never; + + expect(provider.isConfigured({ cfg, providerConfig: {} })).toBe(true); + expect(isProviderAuthProfileConfiguredMock).toHaveBeenCalledWith({ + provider: "openai", + cfg, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }); + }); + + it("does not configure Azure realtime sessions without a Platform API key", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const cfg = { agents: { defaults: {} } } as never; + + expect( + provider.isConfigured({ + cfg, + providerConfig: { + azureEndpoint: "https://example.openai.azure.com", + azureDeployment: "realtime", + }, + }), + ).toBe(false); + }); + + it("requires Platform auth before minting browser realtime client secrets", async () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + if (!provider.createBrowserSession) { + throw new Error("expected OpenAI realtime provider to support browser sessions"); + } + const cfg = { agents: { defaults: {} } } as never; + + await expect( + provider.createBrowserSession({ + cfg, + providerConfig: {}, + instructions: "Be concise.", + }), + ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + }); + + it("uses OPENAI_API_KEY for default GPT browser sessions", async () => { + vi.stubEnv("OPENAI_API_KEY", "test-api-key-env"); + fetchWithSsrFGuardMock.mockResolvedValueOnce({ + response: createJsonResponse({ + client_secret: { value: "client-secret-123" }, + }), + release: vi.fn(async () => undefined), + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + if (!provider.createBrowserSession) { + throw new Error("expected OpenAI realtime provider to support browser sessions"); + } + const cfg = { agents: { defaults: {} } } as never; + + await provider.createBrowserSession({ + cfg, + providerConfig: {}, + model: "gpt-realtime-2", + instructions: "Be concise.", + }); + + expectRecordFields(requireFetchHeaders(), "fetch headers", { + Authorization: "Bearer test-api-key-env", + }); + }); + + it("fails closed when keychain refs cannot be resolved", async () => { + vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_MISSING_TEST"); + resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined); + execFileSyncMock.mockImplementationOnce(() => { + throw new Error("keychain unavailable"); + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + + const bridge = provider.createBridge({ + providerConfig: {}, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + await expect(bridge.connect()).rejects.toThrow( + "OpenAI Realtime voice requires an OpenAI Platform API key", + ); + expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledTimes(1); + }); + + it("fails closed when a configured API-key profile cannot be resolved", async () => { + resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined); + isProviderAuthProfileConfiguredMock.mockReturnValueOnce(true); + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + cfg: {} as never, + providerConfig: {}, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + await expect(bridge.connect()).rejects.toThrow( + "OpenAI Realtime voice requires an OpenAI Platform API key", + ); + expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledTimes(1); + }); + + it("treats pre-ready auth errors as a single startup failure", async () => { + const onError = vi.fn(); + const onClose = vi.fn(); + const bridge = createNativeBridge({ onError, onClose }); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { message: "Incorrect API key provided: test-api-key-proj-***" }, + }), + ), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { message: "Incorrect API key provided: test-api-key-proj-***" }, + }), + ), + ); + + await expect(connecting).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); + expect(onError).not.toHaveBeenCalled(); + expect(onClose).not.toHaveBeenCalled(); + expect(socket.closed).toBe(true); + expect(bridge.isConnected()).toBe(false); + }); + + it("normalizes structured direct OpenAI startup auth errors", async () => { + const bridge = createNativeBridge(); + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { + type: "invalid_request_error", + code: "invalid_api_key", + message: "Invalid API key", + }, + }), + ), + ); + + await expect(connecting).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); + expect(bridge.isConnected()).toBe(false); + }); + + it("normalizes direct OpenAI socket handshake auth errors", async () => { + const bridge = createNativeBridge(); + const { connecting, socket } = beginBridgeConnection(bridge); + + socket.emit("error", new Error("Unexpected server response: 401")); + + await expect(connecting).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); + expect(bridge.isConnected()).toBe(false); + }); + + it.each([ + [ + "Azure deployment", + { + apiKey: "test-api-key-test", + azureEndpoint: "https://example.openai.azure.com", + azureDeployment: "realtime-prod", + }, + ], + [ + "custom endpoint", + { + apiKey: "test-api-key-test", + azureEndpoint: "https://realtime-proxy.example.com", + }, + ], + ])("preserves %s startup auth errors", async (_label, providerConfig) => { + const bridge = createNativeBridge({ + providerConfig, + }); + const { connecting, socket } = beginBridgeConnection(bridge); + + socket.emit("error", new Error("Unexpected server response: 401")); + + await expect(connecting).rejects.toThrow("Unexpected server response: 401"); + expect(bridge.isConnected()).toBe(false); + }); +}); diff --git a/extensions/openai/realtime-voice-events.ts b/extensions/openai/realtime-voice-events.ts new file mode 100644 index 000000000000..a60c04c1607a --- /dev/null +++ b/extensions/openai/realtime-voice-events.ts @@ -0,0 +1,402 @@ +import { canonicalizeBase64 } from "openclaw/plugin-sdk/media-runtime"; +import type { RealtimeVoiceSessionConnection } from "openclaw/plugin-sdk/realtime-voice"; +import { normalizeRealtimeVoiceResponseOutcome } from "openclaw/plugin-sdk/realtime-voice"; +import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime"; +import { readRealtimeErrorDetail } from "./realtime-provider-shared.js"; +import { OpenAIRealtimeProtocol } from "./realtime-voice-protocol.js"; +import { + OPENAI_REALTIME_ACTIVE_RESPONSE_ERROR_PREFIX, + OPENAI_REALTIME_NO_ACTIVE_RESPONSE_CANCEL_ERROR, + isOpenAIRealtimeMaxSessionDurationError, + readRealtimeErrorEventId, + type RealtimeEvent, +} from "./realtime-voice-session-policy.js"; + +export class OpenAIRealtimeMalformedAudioError extends Error {} + +function base64ToBuffer(b64: string): Buffer { + const canonicalAudio = canonicalizeBase64(b64); + if (!canonicalAudio) { + throw new OpenAIRealtimeMalformedAudioError( + "OpenAI realtime stream returned malformed base64 audio data", + ); + } + return Buffer.from(canonicalAudio, "base64"); +} + +export abstract class OpenAIRealtimeEvents extends OpenAIRealtimeProtocol { + protected handleEvent(event: RealtimeEvent, connection: RealtimeVoiceSessionConnection): void { + const emitServerEvent = () => + this.config.onEvent?.({ + direction: "server", + type: event.type, + detail: this.describeServerEvent(event), + ...(event.item_id ? { itemId: event.item_id } : {}), + ...((event.response_id ?? event.response?.id) + ? { responseId: event.response_id ?? event.response?.id } + : {}), + }); + if ( + event.type === "error" && + isOpenAIRealtimeMaxSessionDurationError(readRealtimeErrorDetail(event.error)) + ) { + this.rotateExpiredSession(); + return; + } + if (event.type === "response.done") { + this.handleResponseDone(event, connection, emitServerEvent); + return; + } + if (event.type === "response.cancelled") { + try { + emitServerEvent(); + } finally { + this.releaseResponseState(); + } + return; + } + emitServerEvent(); + switch (event.type) { + case "session.created": + return; + + case "session.updated": { + this.onSessionUpdated(connection); + return; + } + + case "response.created": + this.responseActive = true; + this.responseCreateInFlight = false; + return; + + case "conversation.output_audio.delta": + case "response.audio.delta": + case "response.output_audio.delta": { + const audioDelta = event.delta ?? event.data; + if (!audioDelta) { + return; + } + const audio = base64ToBuffer(audioDelta); + this.config.onAudio(audio); + if (event.item_id && event.item_id !== this.lastAssistantItemId) { + this.lastAssistantItemId = event.item_id; + this.responseStartTimestamp = this.latestMediaTimestamp; + } else if (this.responseStartTimestamp === null) { + this.responseStartTimestamp = this.latestMediaTimestamp; + } + this.responseActive = true; + this.sendMark(); + return; + } + + case "input_audio_buffer.speech_started": + if (this.config.interruptResponseOnInputAudio ?? this.config.autoRespondToAudio ?? true) { + this.handleBargeIn(); + } + return; + + case "conversation.output_transcript.delta": + case "response.text.delta": + case "response.output_text.delta": + case "response.audio_transcript.delta": + case "response.output_audio_transcript.delta": + if (event.delta) { + this.config.onTranscript?.("assistant", event.delta, false); + } + return; + + case "response.text.done": + case "response.output_text.done": + case "response.audio_transcript.done": + case "response.output_audio_transcript.done": + { + const transcript = event.transcript ?? event.text; + if (transcript) { + this.config.onTranscript?.("assistant", transcript, true); + } + } + return; + + case "conversation.input_transcript.delta": + case "conversation.item.input_audio_transcription.delta": + if (event.delta) { + this.config.onTranscript?.("user", event.delta, false); + } + return; + + case "conversation.item.input_audio_transcription.completed": + if (event.transcript) { + this.config.onTranscript?.("user", event.transcript, true); + } + return; + + case "conversation.item.input_audio_transcription.failed": + this.config.onError?.(new Error(readRealtimeErrorDetail(event.error))); + break; + + case "conversation.item.added": + break; + + case "response.function_call_arguments.delta": + case "response.function_call_arguments.done": + case "conversation.item.done": + // These events are provisional and can also arrive for interrupted, + // incomplete, or cancelled responses. Successful response.done output + // is the sole execution boundary. + return; + + case "error": { + const detail = readRealtimeErrorDetail(event.error); + const rejectedEventId = readRealtimeErrorEventId(event.error); + if (rejectedEventId && rejectedEventId === this.standaloneSpeechEventId) { + this.responseCreateInFlight = false; + this.standaloneSpeechActive = false; + this.standaloneSpeechEventId = null; + this.config.onError?.(new Error(detail)); + if (this.standaloneSpeechQueue.length > 0) { + this.flushStandaloneSpeech(); + } else if (this.responseCreatePending) { + this.flushPendingResponseCreate(); + } + return; + } + const rejectsManualResponseCreate = + this.manualResponseCreateEventId !== null && + readRealtimeErrorEventId(event.error) === this.manualResponseCreateEventId; + if ( + rejectsManualResponseCreate && + detail.startsWith(OPENAI_REALTIME_ACTIVE_RESPONSE_ERROR_PREFIX) + ) { + this.responseActive = true; + this.responseCreateInFlight = false; + this.manualResponseCreateEventId = null; + this.responseCreatePending = true; + return; + } + const rejectsManualResponseCancel = + this.manualResponseCancelEventId !== null && + readRealtimeErrorEventId(event.error) === this.manualResponseCancelEventId; + if (detail === OPENAI_REALTIME_NO_ACTIVE_RESPONSE_CANCEL_ERROR) { + if (!rejectsManualResponseCancel) { + return; + } + this.responseActive = false; + this.responseCancelInFlight = false; + this.manualResponseCancelEventId = null; + if (this.responseCreatePending) { + this.flushPendingResponseCreate(); + } else { + this.restoreAutoRespondAfterManualResponse(); + } + return; + } + if (rejectsManualResponseCreate) { + this.responseCreateInFlight = false; + this.manualResponseCreateEventId = null; + if (this.responseCreatePending) { + this.flushPendingResponseCreate(); + } else { + this.restoreAutoRespondAfterManualResponse(); + } + } + this.config.onError?.(new Error(detail)); + } + + default: + } + } + + private handleCompletedResponse( + event: RealtimeEvent, + connection: RealtimeVoiceSessionConnection, + ): boolean { + if ( + event.response?.status !== "completed" || + !Array.isArray(event.response.output) || + !this.config.onToolCall + ) { + return false; + } + for (const output of event.response.output) { + if (!this.acceptsEvent(connection) || !this.isTransportOpen()) { + return true; + } + if ( + !isRecord(output) || + output.type !== "function_call" || + (output.status !== undefined && output.status !== "completed") + ) { + continue; + } + const itemId = typeof output.id === "string" ? output.id.trim() || undefined : undefined; + const callId = typeof output.call_id === "string" ? output.call_id.trim() : ""; + const name = typeof output.name === "string" ? output.name.trim() : ""; + if (!callId || !name || this.completedToolCallIds.has(callId)) { + continue; + } + if (this.completedToolCallIds.size >= OpenAIRealtimeProtocol.MAX_COMPLETED_TOOL_CALL_IDS) { + this.failToolCallSessionLimit( + new Error( + `OpenAI realtime tool-call session limit exceeded (${OpenAIRealtimeProtocol.MAX_COMPLETED_TOOL_CALL_IDS})`, + ), + connection, + ); + return true; + } + this.completedToolCallIds.add(callId); + this.pendingToolCallIds.add(callId); + if (typeof output.arguments !== "string") { + this.rejectToolCallArguments({ + itemId, + callId, + reason: "invalid-json-type", + message: "Invalid tool arguments: expected a JSON object.", + }); + continue; + } + const rawArgs = output.arguments; + if (Buffer.byteLength(rawArgs, "utf8") > OpenAIRealtimeProtocol.MAX_TOOL_ARGUMENT_BYTES) { + this.rejectToolCallArguments({ + itemId, + callId, + reason: "too-large", + message: `Realtime tool arguments exceed the ${OpenAIRealtimeProtocol.MAX_TOOL_ARGUMENT_BYTES}-byte UTF-8 limit`, + }); + continue; + } + let args: unknown; + try { + args = JSON.parse(rawArgs || "{}"); + } catch { + this.rejectToolCallArguments({ + itemId, + callId, + reason: "malformed-json", + message: "Invalid tool arguments: expected a JSON object.", + }); + continue; + } + if (!isRecord(args)) { + this.rejectToolCallArguments({ + itemId, + callId, + reason: "non-object-json", + message: "Invalid tool arguments: expected a JSON object.", + }); + continue; + } + this.config.onToolCall({ itemId: itemId ?? callId, callId, name, args }); + } + return false; + } + + private handleResponseDone( + event: RealtimeEvent, + connection: RealtimeVoiceSessionConnection, + emitServerEvent: () => void, + ): void { + const outcome = normalizeRealtimeVoiceResponseOutcome({ + providerLabel: "OpenAI realtime voice", + response: event.response, + responseId: event.response_id, + }); + let callbackError: unknown; + let providerTerminated = false; + const invoke = (callback: () => void) => { + try { + callback(); + } catch (error) { + callbackError ??= error; + } + }; + try { + invoke(() => this.config.onResponseDone?.(outcome)); + invoke(emitServerEvent); + invoke(() => { + providerTerminated = this.handleCompletedResponse(event, connection); + }); + } finally { + // response.done owns response state regardless of observer success. A fatal tool + // boundary still clears state, but must not start queued work on a closing socket. + const canDrain = + !providerTerminated && this.acceptsEvent(connection) && this.isTransportOpen(); + this.releaseResponseState({ drain: canDrain }); + } + if (callbackError) { + throw callbackError instanceof Error + ? callbackError + : new Error("OpenAI realtime response callback failed", { cause: callbackError }); + } + } + + private rejectToolCallArguments(params: { + itemId?: string; + callId: string; + reason: string; + message: string; + }): void { + this.config.onEvent?.({ + direction: "server", + type: "tool_call.arguments.rejected", + detail: `reason=${params.reason}`, + itemId: params.itemId, + }); + this.submitToolResult(params.callId, { error: params.message }); + } + + private describeServerEvent(event: RealtimeEvent): string | undefined { + if ( + event.type === "error" || + event.type === "conversation.item.input_audio_transcription.failed" + ) { + return readRealtimeErrorDetail(event.error); + } + if (event.type === "session.created" || event.type === "session.updated") { + const session = isRecord(event.session) ? event.session : undefined; + const tools = Array.isArray(session?.tools) ? session.tools.length : 0; + const rawToolChoice = session?.tool_choice; + const toolChoice = + typeof rawToolChoice === "string" + ? rawToolChoice + : isRecord(rawToolChoice) && typeof rawToolChoice.type === "string" + ? rawToolChoice.type + : "unset"; + return `tools=${tools} toolChoice=${toolChoice}`; + } + if ( + (event.type === "conversation.item.added" || event.type === "conversation.item.done") && + event.item?.type + ) { + return [ + `itemType=${event.item.type}`, + event.item.name ? `name=${event.item.name}` : undefined, + ] + .filter(Boolean) + .join(" "); + } + if (event.type === "response.done") { + const status = event.response?.status; + const details = + event.response?.status_details === undefined + ? undefined + : JSON.stringify(event.response.status_details); + return ( + [status ? `status=${status}` : undefined, details].filter(Boolean).join(" ") || undefined + ); + } + if (event.type === "response.cancelled") { + return "cancelled"; + } + return undefined; + } + + protected abstract acceptsEvent(connection: RealtimeVoiceSessionConnection): boolean; + protected abstract isTransportOpen(): boolean; + protected abstract onSessionUpdated(connection: RealtimeVoiceSessionConnection): void; + protected abstract rotateExpiredSession(): void; + protected abstract failToolCallSessionLimit( + error: Error, + connection: RealtimeVoiceSessionConnection, + ): void; +} diff --git a/extensions/openai/realtime-voice-protocol.ts b/extensions/openai/realtime-voice-protocol.ts new file mode 100644 index 000000000000..513d1ff832a2 --- /dev/null +++ b/extensions/openai/realtime-voice-protocol.ts @@ -0,0 +1,417 @@ +import { randomUUID } from "node:crypto"; +import type { + RealtimeVoiceAudioFormat, + RealtimeVoiceBargeInOptions, + RealtimeVoiceToolResultOptions, +} from "openclaw/plugin-sdk/realtime-voice"; +import { REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ } from "openclaw/plugin-sdk/realtime-voice"; +import { + AZURE_OPENAI_REALTIME_TOOL_NAME_MAX_LENGTH, + OPENAI_REALTIME_DEFAULT_MIN_BARGE_IN_AUDIO_END_MS, + OPENAI_REALTIME_DEFAULT_MODEL, + buildOpenAIRealtimeGaSessionPolicy, + buildOpenAIRealtimeTurnDetectionConfig, + normalizeOpenAIRealtimeTools, + parsePlaybackMarkSequence, + type OpenAIRealtimeUserMessageOptions, + type OpenAIRealtimeVoiceBridgeConfig, + type RealtimeAzureDeploymentSessionUpdate, + type RealtimeGaSessionUpdate, + type RealtimeTurnDetectionConfig, +} from "./realtime-voice-session-policy.js"; + +export abstract class OpenAIRealtimeProtocol { + static readonly MAX_TOOL_ARGUMENT_BYTES = 256_000; + + // Realtime defines no replay window. Keep every terminal id for this + // connection generation, then fail instead of re-admitting late duplicates. + static readonly MAX_COMPLETED_TOOL_CALL_IDS = 1_024; + + readonly supportsToolResultContinuation = true; + + readonly supportsToolResultSuppression = true; + + protected nextMarkSequence = 1; + + protected oldestOutstandingMarkSequence: number | null = null; + + protected latestOutstandingMarkSequence: number | null = null; + + protected responseStartTimestamp: number | null = null; + + protected responseActive = false; + + protected responseCreateInFlight = false; + + protected manualResponseCreateEventId: string | null = null; + + protected responseCancelInFlight = false; + + protected manualResponseCancelEventId: string | null = null; + + protected responseCreatePending = false; + + protected autoRespondSuppressedForManualResponse = false; + + protected continuingToolCallIds = new Set(); + + protected pendingToolCallIds = new Set(); + + protected latestMediaTimestamp = 0; + + protected lastAssistantItemId: string | null = null; + + protected completedToolCallIds = new Set(); + + protected standaloneSpeechQueue: string[] = []; + + protected standaloneSpeechActive = false; + + protected standaloneSpeechEventId: string | null = null; + + private readonly audioFormat: RealtimeVoiceAudioFormat; + + constructor(protected readonly config: OpenAIRealtimeVoiceBridgeConfig) { + this.audioFormat = config.audioFormat ?? REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ; + } + + setMediaTimestamp(ts: number): void { + this.latestMediaTimestamp = ts; + } + + acknowledgeMark(markName?: string): void { + const oldest = this.oldestOutstandingMarkSequence; + const latest = this.latestOutstandingMarkSequence; + if (oldest === null || latest === null) { + return; + } + const acknowledgedSequence = + markName === undefined ? oldest : parsePlaybackMarkSequence(markName); + if ( + acknowledgedSequence === undefined || + acknowledgedSequence < oldest || + acknowledgedSequence > latest + ) { + return; + } + // Marks follow ordered playback. Reaching a named mark also acknowledges every + // earlier mark, while late acknowledgements from that prefix remain harmless. + if (acknowledgedSequence === latest) { + this.oldestOutstandingMarkSequence = null; + this.latestOutstandingMarkSequence = null; + return; + } + this.oldestOutstandingMarkSequence = acknowledgedSequence + 1; + } + + protected sendSessionUpdate(): void { + if (this.usesAzureDeploymentRealtimeApi()) { + this.sendEvent(this.buildAzureDeploymentSessionUpdate()); + return; + } + + this.sendEvent(this.buildGaSessionUpdate()); + } + + protected buildGaSessionUpdate(): RealtimeGaSessionUpdate { + const cfg = this.config; + return { + type: "session.update", + session: + cfg.gaSessionPolicy ?? + buildOpenAIRealtimeGaSessionPolicy({ + audioFormat: this.audioFormat, + autoRespondToAudio: cfg.autoRespondToAudio, + instructions: cfg.instructions, + interruptResponseOnInputAudio: cfg.interruptResponseOnInputAudio, + language: cfg.language, + model: cfg.model ?? OPENAI_REALTIME_DEFAULT_MODEL, + noiseReduction: null, + prefixPaddingMs: cfg.prefixPaddingMs, + reasoningEffort: cfg.reasoningEffort, + silenceDurationMs: cfg.silenceDurationMs, + tools: normalizeOpenAIRealtimeTools(cfg.tools), + vadThreshold: cfg.vadThreshold, + voice: cfg.voice ?? "alloy", + }), + }; + } + + protected usesAzureDeploymentRealtimeApi(): boolean { + return Boolean(this.config.azureEndpoint && this.config.azureDeployment); + } + + protected buildAzureDeploymentSessionUpdate(): RealtimeAzureDeploymentSessionUpdate { + const cfg = this.config; + const format = this.resolveLegacyRealtimeAudioFormat(); + const tools = normalizeOpenAIRealtimeTools( + cfg.tools, + AZURE_OPENAI_REALTIME_TOOL_NAME_MAX_LENGTH, + ); + return { + type: "session.update", + session: { + modalities: ["text", "audio"], + instructions: cfg.instructions, + voice: cfg.voice ?? "alloy", + input_audio_format: format, + output_audio_format: format, + input_audio_transcription: { + model: "whisper-1", + ...(cfg.language ? { language: cfg.language } : {}), + }, + turn_detection: this.buildTurnDetectionConfig(), + temperature: cfg.temperature ?? 0.8, + ...(tools + ? { + tools, + tool_choice: "auto", + } + : {}), + }, + }; + } + + protected buildTurnDetectionConfig(options?: { + createResponse?: boolean; + includeInterruptResponse?: boolean; + }): RealtimeTurnDetectionConfig { + return buildOpenAIRealtimeTurnDetectionConfig({ + autoRespondToAudio: this.config.autoRespondToAudio, + createResponse: options?.createResponse, + includeInterruptResponse: options?.includeInterruptResponse, + interruptResponseOnInputAudio: this.config.interruptResponseOnInputAudio, + prefixPaddingMs: this.config.prefixPaddingMs, + silenceDurationMs: this.config.silenceDurationMs, + vadThreshold: this.config.vadThreshold, + }); + } + + protected sendAutoResponseSessionUpdate(createResponse: boolean): void { + const azureDeployment = this.usesAzureDeploymentRealtimeApi(); + const turnDetection = this.buildTurnDetectionConfig({ + createResponse, + includeInterruptResponse: !azureDeployment, + }); + if (azureDeployment) { + this.sendEvent({ type: "session.update", session: { turn_detection: turnDetection } }); + return; + } + this.sendEvent({ + type: "session.update", + session: { type: "realtime", audio: { input: { turn_detection: turnDetection } } }, + }); + } + + protected resolveLegacyRealtimeAudioFormat(): "g711_ulaw" | "pcm16" { + return this.audioFormat.encoding === "pcm16" ? "pcm16" : "g711_ulaw"; + } + + protected releaseResponseState(options: { drain?: boolean } = {}): void { + this.responseActive = false; + this.responseCreateInFlight = false; + this.manualResponseCreateEventId = null; + this.responseCancelInFlight = false; + this.manualResponseCancelEventId = null; + if (this.standaloneSpeechActive) { + this.standaloneSpeechActive = false; + this.standaloneSpeechEventId = null; + } + if (options.drain === false) { + return; + } + if (this.standaloneSpeechQueue.length > 0) { + this.flushStandaloneSpeech(); + } else if (this.responseCreatePending) { + this.flushPendingResponseCreate(); + } else { + this.restoreAutoRespondAfterManualResponse(); + } + } + + handleBargeIn(options?: RealtimeVoiceBargeInOptions): void { + const assistantItemId = this.lastAssistantItemId; + const responseStartTimestamp = this.responseStartTimestamp; + const force = options?.force === true; + const shouldInterruptProvider = + assistantItemId !== null && + ((responseStartTimestamp !== null && + (this.oldestOutstandingMarkSequence !== null || options?.audioPlaybackActive === true)) || + force); + const audioEndMs = shouldInterruptProvider + ? Math.max( + 0, + responseStartTimestamp === null + ? this.latestMediaTimestamp + : this.latestMediaTimestamp - responseStartTimestamp, + ) + : null; + const minBargeInAudioEndMs = + this.config.minBargeInAudioEndMs ?? OPENAI_REALTIME_DEFAULT_MIN_BARGE_IN_AUDIO_END_MS; + if (!force && audioEndMs !== null && audioEndMs < minBargeInAudioEndMs) { + this.config.onEvent?.({ + direction: "client", + type: "conversation.item.truncate.skipped", + detail: `reason=barge-in audioEndMs=${audioEndMs} minAudioEndMs=${minBargeInAudioEndMs}`, + }); + return; + } + if ( + options?.audioPlaybackActive === true && + this.responseActive && + !this.responseCancelInFlight + ) { + const eventId = `openclaw-response-cancel-${randomUUID()}`; + this.manualResponseCancelEventId = eventId; + this.sendEvent({ type: "response.cancel", event_id: eventId }, "reason=barge-in"); + this.responseCancelInFlight = true; + } + if (shouldInterruptProvider) { + this.sendEvent( + { + type: "conversation.item.truncate", + item_id: assistantItemId, + content_index: 0, + audio_end_ms: audioEndMs, + }, + `reason=barge-in audioEndMs=${audioEndMs}`, + ); + this.config.onClearAudio("barge-in"); + this.clearOutstandingMarks(); + this.lastAssistantItemId = null; + this.responseStartTimestamp = null; + return; + } + this.config.onClearAudio("barge-in"); + } + + protected requestResponseCreate(options?: OpenAIRealtimeUserMessageOptions): void { + if ( + this.responseActive || + this.responseCreateInFlight || + this.responseCancelInFlight || + this.continuingToolCallIds.size > 0 || + this.pendingToolCallIds.size > 0 + ) { + this.responseCreatePending = true; + return; + } + this.responseCreatePending = false; + this.responseCreateInFlight = true; + this.suppressAutoRespondForManualResponse(); + const eventId = `openclaw-response-create-${randomUUID()}`; + // Realtime errors can describe unrelated client events. Keep this id until + // the manual turn settles so only its rejection may release VAD suppression. + this.manualResponseCreateEventId = eventId; + this.sendEvent({ + type: "response.create", + event_id: eventId, + ...(options?.toolChoice + ? { response: { output_modalities: ["audio"], tool_choice: options.toolChoice } } + : {}), + }); + } + + protected flushStandaloneSpeech(): void { + if ( + this.standaloneSpeechActive || + this.responseActive || + this.responseCreateInFlight || + this.responseCancelInFlight + ) { + return; + } + const text = this.standaloneSpeechQueue.shift(); + if (!text) { + return; + } + const eventId = `openclaw-standalone-speech-${randomUUID()}`; + this.standaloneSpeechActive = true; + this.standaloneSpeechEventId = eventId; + this.responseCreateInFlight = true; + this.sendEvent({ + type: "response.create", + event_id: eventId, + response: { + conversation: "none", + output_modalities: ["audio"], + input: [ + { + type: "message", + role: "user", + content: [{ type: "input_text", text }], + }, + ], + }, + }); + } + + protected suppressAutoRespondForManualResponse(): void { + if (this.config.autoRespondToAudio === false || this.autoRespondSuppressedForManualResponse) { + return; + } + // Manual response.create owns this turn. Keep VAD events and interruption active, + // but prevent a second server-owned response until all queued manual work finishes. + this.autoRespondSuppressedForManualResponse = true; + this.sendAutoResponseSessionUpdate(false); + } + + protected restoreAutoRespondAfterManualResponse(): void { + if (!this.autoRespondSuppressedForManualResponse) { + return; + } + this.autoRespondSuppressedForManualResponse = false; + this.sendAutoResponseSessionUpdate(true); + } + + protected flushPendingResponseCreate(): void { + if (!this.responseCreatePending) { + return; + } + this.responseCreatePending = false; + this.requestResponseCreate(); + } + + protected resetRealtimeSessionState(): void { + this.clearOutstandingMarks(); + this.responseStartTimestamp = null; + this.responseActive = false; + this.responseCreateInFlight = false; + this.manualResponseCreateEventId = null; + this.responseCancelInFlight = false; + this.manualResponseCancelEventId = null; + this.responseCreatePending = false; + this.autoRespondSuppressedForManualResponse = false; + this.continuingToolCallIds.clear(); + this.pendingToolCallIds.clear(); + this.lastAssistantItemId = null; + this.completedToolCallIds.clear(); + this.standaloneSpeechQueue = []; + this.standaloneSpeechActive = false; + this.standaloneSpeechEventId = null; + } + + protected sendMark(): void { + const sequence = this.nextMarkSequence; + this.nextMarkSequence += 1; + if (this.oldestOutstandingMarkSequence === null) { + this.oldestOutstandingMarkSequence = sequence; + } + this.latestOutstandingMarkSequence = sequence; + const markName = `audio-${sequence}`; + this.config.onMark?.(markName); + } + + protected clearOutstandingMarks(): void { + this.oldestOutstandingMarkSequence = null; + this.latestOutstandingMarkSequence = null; + } + + abstract submitToolResult( + callId: string, + result: unknown, + options?: RealtimeVoiceToolResultOptions, + ): void; + + protected abstract sendEvent(event: unknown, detail?: string): void; +} diff --git a/extensions/openai/realtime-voice-provider-routing.test.ts b/extensions/openai/realtime-voice-provider-routing.test.ts new file mode 100644 index 000000000000..22946a22111a --- /dev/null +++ b/extensions/openai/realtime-voice-provider-routing.test.ts @@ -0,0 +1,756 @@ +// Openai tests cover realtime voice provider plugin behavior. +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { buildOpenAIRealtimeVoiceProvider } from "./realtime-voice-provider.js"; + +const INTERNAL_REALTIME_VOICE_PROVIDER = Symbol.for("openclaw.internal.realtime-voice-provider.v1"); + +function readInternalRealtimeVoiceProviderApi(provider: object) { + return Reflect.get(provider, INTERNAL_REALTIME_VOICE_PROVIDER) as { + isBrowserSessionConfigured: (ctx: { + cfg?: object; + providerConfig: Record; + agentId?: string; + }) => boolean; + isGatewayRelayConfigured: (ctx: { + cfg?: object; + providerConfig: Record; + agentId?: string; + }) => boolean | undefined; + resolveBrowserSessionCapabilities: (ctx: { + cfg?: object; + providerConfig: Record; + model?: string; + }) => { + handlesAgentConsult?: boolean; + supportsToolCalls?: boolean; + supportsVideoFrames?: boolean; + supportsGatewayControl?: boolean; + transports?: string[]; + }; + resolveGatewayRelayCapabilities: (ctx: { + cfg?: object; + providerConfig: Record; + model?: string; + }) => { + handlesAgentConsult?: boolean; + supportsToolCalls?: boolean; + transports?: string[]; + }; + validateGatewayRelayLaunch: (ctx: { + cfg?: object; + providerConfig: Record; + model?: string; + autoRespondToAudio?: boolean; + }) => string | undefined; + cancelBrowserSession: (request: Record, session: object) => Promise; + }; +} + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + createJsonResponse, + requireRecord, + requireFetchJsonBody, + createRealtimeTool, + createUnreadableToolName, + createMalformedToolName, + createTestJwt, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice provider routing", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("declares realtime Talk capabilities for catalog selection", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + + expect(provider.defaultModel).toBe("gpt-realtime-2.1"); + expect(provider.capabilities).toEqual({ + transports: ["webrtc", "gateway-relay"], + inputAudioFormats: [ + { encoding: "g711_ulaw", sampleRateHz: 8000, channels: 1 }, + { encoding: "pcm16", sampleRateHz: 24000, channels: 1 }, + ], + outputAudioFormats: [ + { encoding: "g711_ulaw", sampleRateHz: 8000, channels: 1 }, + { encoding: "pcm16", sampleRateHz: 24000, channels: 1 }, + ], + supportsBrowserSession: true, + supportsBargeIn: true, + handlesInputAudioBargeIn: true, + supportsToolCalls: true, + supportsVideoFrames: true, + }); + }); + + it("advertises continuing realtime tool results", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const bridge = provider.createBridge({ + providerConfig: { apiKey: "test-api-key-test" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + }); + + expect(bridge.supportsToolResultContinuation).toBe(true); + expect(bridge.supportsToolResultSuppression).toBe(true); + }); + + it("advertises quicksilver capabilities only for curated /v1/live models", () => { + const quicksilverBroker = { + capabilities: { + transports: ["webrtc" as const], + handlesAgentConsult: true as const, + supportsToolCalls: false, + supportsVideoFrames: false, + }, + createBrowserSession: vi.fn(), + cancelBrowserSession: vi.fn(), + }; + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: quicksilverBroker, + }); + const internalApi = readInternalRealtimeVoiceProviderApi(provider); + + expect( + internalApi.resolveBrowserSessionCapabilities({ + providerConfig: { model: "gpt-realtime-2.1" }, + model: "gpt-live-1-codex", + }), + ).toMatchObject({ + transports: ["webrtc", "gateway-relay"], + handlesAgentConsult: true, + supportsToolCalls: false, + supportsVideoFrames: false, + }); + expect( + internalApi.resolveGatewayRelayCapabilities({ + providerConfig: { model: "gpt-realtime-2.1" }, + model: "gpt-live-1-codex", + }), + ).toMatchObject({ + transports: ["webrtc", "gateway-relay"], + handlesAgentConsult: true, + supportsToolCalls: false, + }); + expect( + internalApi.resolveBrowserSessionCapabilities({ + providerConfig: { model: "gpt-realtime-2.1" }, + model: "gpt-live-1-mini", + }), + ).not.toHaveProperty("handlesAgentConsult"); + expect( + internalApi.resolveGatewayRelayCapabilities({ + providerConfig: { model: "gpt-realtime-2.1" }, + model: "gpt-live-1-mini", + }), + ).not.toHaveProperty("handlesAgentConsult"); + }); + + it("omits unsupported OpenAI tool names from browser sessions", async () => { + fetchWithSsrFGuardMock.mockResolvedValueOnce({ + response: createJsonResponse({ client_secret: { value: "client-secret-123" } }), + release: vi.fn(async () => undefined), + }); + const provider = buildOpenAIRealtimeVoiceProvider(); + if (!provider.createBrowserSession) { + throw new Error("expected OpenAI realtime provider to support browser sessions"); + } + + await provider.createBrowserSession({ + providerConfig: { apiKey: "test-api-key-test" }, + tools: [ + createRealtimeTool("1_lookup"), + createRealtimeTool("calendar.lookup:next"), + createMalformedToolName(undefined), + createUnreadableToolName(), + ], + }); + + const bodySession = requireRecord(requireFetchJsonBody().session, "fetch session"); + const tools = bodySession.tools as Array<{ name?: string }>; + expect(tools.map((tool) => tool.name)).toEqual(["1_lookup"]); + }); + + it("does not resolve keychain refs during configured checks", () => { + vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_CONFIGURED_TEST"); + const provider = buildOpenAIRealtimeVoiceProvider(); + + expect(provider.isConfigured({ providerConfig: {} })).toBe(true); + expect(execFileSyncMock).not.toHaveBeenCalled(); + }); + + it("does not treat Codex OAuth profiles as configured for realtime sessions", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const cfg = { agents: { defaults: {} } } as never; + + expect(provider.isConfigured({ cfg, providerConfig: {} })).toBe(false); + expect(isProviderAuthProfileConfiguredMock).toHaveBeenCalledWith({ + provider: "openai", + cfg, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }); + }); + + it("routes gpt-live Platform sessions through the native quicksilver broker", async () => { + const createBrowserSession = vi.fn(async (_request: unknown, _auth: unknown) => ({ + provider: "openai", + transport: "webrtc" as const, + clientSecret: "quicksilver-token", + offerUrl: "/plugins/openai/realtime/calls", + })); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { + transports: ["webrtc" as const], + handlesAgentConsult: true as const, + supportsToolCalls: false, + supportsVideoFrames: false, + }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + const request = { + providerConfig: { apiKey: "test-api-key-platform" }, + model: "gpt-live-1", + agentId: "main", + workspaceDir: "/tmp/openclaw-agent-workspace", + initialItems: [], + runAgentConsult: vi.fn(async () => ({ text: "Done" })), + }; + + await expect(provider.createBrowserSession?.(request)).resolves.toMatchObject({ + offerUrl: "/plugins/openai/realtime/calls", + }); + expect(createBrowserSession).toHaveBeenCalledWith(expect.objectContaining(request), { + type: "api-key", + token: "test-api-key-platform", + }); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + }); + + it("routes an explicit unlisted gpt-live alias without advertising it as ready", async () => { + const oauthToken = createTestJwt({ + "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, + }); + resolveProviderAuthProfileApiKeyMock.mockImplementation( + async ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") ? oauthToken : undefined, + ); + isProviderAuthProfileConfiguredMock.mockImplementation( + ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") === true, + ); + const createBrowserSession = vi.fn(async () => ({ + provider: "openai", + transport: "webrtc" as const, + clientSecret: "quicksilver-token", + offerUrl: "/plugins/openai/realtime/calls", + })); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { + transports: ["webrtc" as const], + handlesAgentConsult: true as const, + supportsToolCalls: false, + supportsVideoFrames: false, + }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + const cfg = { agents: { defaults: {} } } as never; + const request = { + cfg, + providerConfig: {}, + model: "gpt-live-1-mini", + agentId: "main", + workspaceDir: "/tmp/openclaw-agent-workspace", + initialItems: [], + runAgentConsult: vi.fn(async () => ({ text: "Done" })), + }; + + expect(provider.isConfigured({ cfg, providerConfig: { model: "gpt-live-1-mini" } })).toBe( + false, + ); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-mini" }, + agentId: "main", + }), + ).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { + model: "gpt-live-1-mini", + azureEndpoint: "https://example.openai.azure.com", + azureDeployment: "gpt-live", + }, + agentId: "main", + }), + ).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-mini" }, + agentId: "main", + }), + ).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { model: "gpt-realtime-2.1", apiKey: "test-api-key-platform" }, + agentId: "main", + }), + ).toBeUndefined(); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { + model: "gpt-realtime-2.1", + apiKey: "test-api-key-platform", + azureEndpoint: "https://example.openai.azure.com", + }, + agentId: "main", + }), + ).toBeUndefined(); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { + model: "gpt-live-1-codex", + apiKey: "test-api-key-platform", + azureEndpoint: "https://example.openai.azure.com", + }, + agentId: "main", + }), + ).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-mini", apiKey: "test-api-key-platform" }, + agentId: "main", + }), + ).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-mini", apiKey: "test-api-key-platform" }, + agentId: "main", + }), + ).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-codex" }, + agentId: "main", + }), + ).toBe(true); + expect( + readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-codex" }, + agentId: "voice-agent", + }), + ).toBe(true); + expect(isProviderAuthProfileConfiguredMock).toHaveBeenCalledWith( + expect.objectContaining({ + agentDir: expect.stringContaining("voice-agent"), + profileTypes: ["oauth"], + }), + ); + expect( + readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ + cfg, + providerConfig: { model: "gpt-live-1-codex" }, + agentId: "main", + }), + ).toBe(true); + await provider.createBrowserSession?.(request); + expect(createBrowserSession).toHaveBeenCalledWith(expect.objectContaining(request), { + type: "oauth", + token: oauthToken, + accountId: "account-123", + }); + expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledWith( + expect.objectContaining({ + provider: "openai", + profileTypes: ["oauth"], + includeExternalCliAuth: false, + }), + ); + }); + + it("rejects forced consult routing for prefix-routed gpt-live sessions", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const internalApi = readInternalRealtimeVoiceProviderApi(provider); + + expect( + internalApi.validateGatewayRelayLaunch({ + providerConfig: { model: "gpt-live-future-alias" }, + autoRespondToAudio: false, + }), + ).toContain("cannot use forced agent consult routing"); + expect( + internalApi.validateGatewayRelayLaunch({ + providerConfig: { model: "gpt-realtime-2.1" }, + autoRespondToAudio: false, + }), + ).toBeUndefined(); + }); + + it("prefers ChatGPT OAuth over Platform auth for gpt-live", async () => { + const oauthToken = createTestJwt({ + "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, + }); + resolveProviderAuthProfileApiKeyMock.mockImplementation( + async ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") ? oauthToken : undefined, + ); + const createBrowserSession = vi.fn(async () => ({ + provider: "openai", + transport: "webrtc" as const, + clientSecret: "quicksilver-token", + offerUrl: "/plugins/openai/realtime/calls", + })); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { handlesAgentConsult: true as const }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + + await provider.createBrowserSession?.({ + providerConfig: { apiKey: "test-api-key-platform" }, + model: "gpt-live-1-codex", + agentId: "main", + workspaceDir: "/tmp/openclaw-agent-workspace", + initialItems: [], + runAgentConsult: vi.fn(async () => ({ text: "Done" })), + } as never); + + expect(createBrowserSession).toHaveBeenCalledWith(expect.any(Object), { + type: "oauth", + token: oauthToken, + accountId: "account-123", + }); + }); + + it("does not advertise GA Gateway control for OAuth-only browser auth", () => { + isProviderAuthProfileConfiguredMock.mockImplementation( + ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") === true, + ); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { handlesAgentConsult: true as const }, + createBrowserSession: vi.fn(), + cancelBrowserSession: vi.fn(async () => undefined), + }, + }); + expect( + readInternalRealtimeVoiceProviderApi(provider).resolveBrowserSessionCapabilities({ + cfg: {}, + providerConfig: {}, + model: "gpt-realtime-2.1", + }), + ).not.toHaveProperty("supportsGatewayControl"); + }); + + it("uses ChatGPT OAuth as the browser-only fallback for GA realtime", async () => { + const oauthToken = createTestJwt({ + "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, + }); + resolveProviderAuthProfileApiKeyMock.mockImplementation( + async ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") ? oauthToken : undefined, + ); + isProviderAuthProfileConfiguredMock.mockImplementation( + ({ profileTypes }: { profileTypes?: readonly string[] }) => + profileTypes?.includes("oauth") === true, + ); + const createBrowserSession = vi.fn(async () => ({ + provider: "openai", + transport: "webrtc" as const, + clientSecret: "broker-token", + offerUrl: "/plugins/openai/realtime/calls", + })); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { handlesAgentConsult: true as const }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + const cfg = { agents: { defaults: {} } } as never; + const request = { + cfg, + providerConfig: {}, + model: "gpt-realtime-2.1", + voice: "cedar", + agentId: "main", + workspaceDir: "/tmp/openclaw-agent-workspace", + initialItems: [], + }; + + expect(provider.isConfigured({ cfg, providerConfig: {} })).toBe(false); + expect( + readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ + cfg, + providerConfig: { model: "gpt-realtime-2.1" }, + agentId: "main", + }), + ).toBe(true); + await expect(provider.createBrowserSession?.(request)).resolves.toMatchObject({ + clientSecret: "broker-token", + offerUrl: "/plugins/openai/realtime/calls", + }); + expect(createBrowserSession).toHaveBeenCalledWith( + expect.objectContaining({ model: "gpt-realtime-2.1", voice: "cedar" }), + { type: "oauth", token: oauthToken, accountId: "account-123" }, + ); + expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); + }); + + it("passes configured gpt-live model and voice to the native broker", async () => { + const createBrowserSession = vi.fn(async (_request: unknown, _auth: unknown) => ({ + provider: "openai", + transport: "webrtc" as const, + clientSecret: "quicksilver-token", + offerUrl: "/plugins/openai/realtime/calls", + })); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { + transports: ["webrtc" as const], + handlesAgentConsult: true as const, + supportsToolCalls: false, + supportsVideoFrames: false, + }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + + await provider.createBrowserSession?.({ + providerConfig: { + apiKey: "test-api-key-platform", + model: "gpt-live-1", + speakerVoice: "cedar", + }, + instructions: "Always address the caller as Captain.", + agentId: "voice-agent", + workspaceDir: "/tmp/openclaw-agent-workspace", + initialItems: [], + runAgentConsult: vi.fn(async () => ({ text: "Done" })), + } as never); + + expect(createBrowserSession).toHaveBeenCalledWith( + expect.objectContaining({ model: "gpt-live-1", voice: "cedar" }), + { type: "api-key", token: "test-api-key-platform" }, + ); + const quicksilverRequest = requireRecord( + createBrowserSession.mock.calls[0]?.[0], + "quicksilver request", + ); + expect(quicksilverRequest.instructions).toMatch(/^You are OpenClaw's realtime voice layer\./); + expect(quicksilverRequest.instructions).toContain( + "Context on the commentary channel is silent background", + ); + expect(quicksilverRequest.instructions).toContain( + "Context on the speakable channel is your answer", + ); + expect(quicksilverRequest.instructions).toMatch(/Always address the caller as Captain\.$/); + }); + + it("explains both gpt-live authentication options when neither is available", async () => { + const createBrowserSession = vi.fn(); + const provider = buildOpenAIRealtimeVoiceProvider({ + quicksilverBrowserSessionBroker: { + capabilities: { + transports: ["webrtc" as const], + handlesAgentConsult: true as const, + supportsToolCalls: false, + supportsVideoFrames: false, + }, + createBrowserSession, + cancelBrowserSession: vi.fn(), + }, + }); + + await expect( + provider.createBrowserSession?.({ + providerConfig: {}, + model: "gpt-live-1", + }), + ).rejects.toThrow( + "GPT-Live Talk requires either an OpenAI Platform API key or a ChatGPT OAuth subscription profile", + ); + expect(createBrowserSession).not.toHaveBeenCalled(); + }); + + it("normalizes provider-owned voice settings from raw provider config", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const resolved = provider.resolveConfig?.({ + cfg: {} as never, + rawConfig: { + providers: { + openai: { + model: "gpt-realtime-2", + voice: " Verse ", + temperature: 0.6, + silenceDurationMs: 850, + vadThreshold: 0.35, + reasoningEffort: "low", + }, + }, + }, + }); + + expect(resolved).toEqual({ + model: "gpt-realtime-2", + voice: "verse", + temperature: 0.6, + silenceDurationMs: 850, + vadThreshold: 0.35, + reasoningEffort: "low", + }); + }); + + it("drops malformed realtime voice numeric settings", () => { + const provider = buildOpenAIRealtimeVoiceProvider(); + const resolved = provider.resolveConfig?.({ + cfg: {} as never, + rawConfig: { + providers: { + openai: { + vadThreshold: 1.5, + silenceDurationMs: -1, + prefixPaddingMs: 10.5, + minBargeInAudioEndMs: 25.5, + }, + }, + }, + }); + + expect(resolved?.vadThreshold).toBeUndefined(); + expect(resolved?.silenceDurationMs).toBeUndefined(); + expect(resolved?.prefixPaddingMs).toBeUndefined(); + expect(resolved?.minBargeInAudioEndMs).toBeUndefined(); + }); +}); diff --git a/extensions/openai/realtime-voice-provider.test.ts b/extensions/openai/realtime-voice-provider.test.ts deleted file mode 100644 index 7439acbf17e7..000000000000 --- a/extensions/openai/realtime-voice-provider.test.ts +++ /dev/null @@ -1,4259 +0,0 @@ -// Openai tests cover realtime voice provider plugin behavior. -import { REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ } from "openclaw/plugin-sdk/realtime-voice"; -import type { - RealtimeVoiceBridge, - RealtimeVoiceBridgeCreateRequest, - RealtimeVoiceBridgeEvent, - RealtimeVoiceTool, -} from "openclaw/plugin-sdk/realtime-voice"; -import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime"; -import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import { buildOpenAIRealtimeVoiceProvider } from "./realtime-voice-provider.js"; - -const INTERNAL_REALTIME_VOICE_PROVIDER = Symbol.for("openclaw.internal.realtime-voice-provider.v1"); -const OPENAI_REALTIME_REJECTED_KEY_MESSAGE = - "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source"; - -function readInternalRealtimeVoiceProviderApi(provider: object) { - return Reflect.get(provider, INTERNAL_REALTIME_VOICE_PROVIDER) as { - isBrowserSessionConfigured: (ctx: { - cfg?: object; - providerConfig: Record; - agentId?: string; - }) => boolean; - isGatewayRelayConfigured: (ctx: { - cfg?: object; - providerConfig: Record; - agentId?: string; - }) => boolean | undefined; - resolveBrowserSessionCapabilities: (ctx: { - cfg?: object; - providerConfig: Record; - model?: string; - }) => { - handlesAgentConsult?: boolean; - supportsToolCalls?: boolean; - supportsVideoFrames?: boolean; - supportsGatewayControl?: boolean; - transports?: string[]; - }; - resolveGatewayRelayCapabilities: (ctx: { - cfg?: object; - providerConfig: Record; - model?: string; - }) => { - handlesAgentConsult?: boolean; - supportsToolCalls?: boolean; - transports?: string[]; - }; - validateGatewayRelayLaunch: (ctx: { - cfg?: object; - providerConfig: Record; - model?: string; - autoRespondToAudio?: boolean; - }) => string | undefined; - cancelBrowserSession: (request: Record, session: object) => Promise; - }; -} - -const { - FakeWebSocket, - execFileSyncMock, - fetchWithSsrFGuardMock, - isProviderAuthProfileConfiguredMock, - resolveProviderAuthProfileApiKeyMock, -} = vi.hoisted(() => { - type Listener = (...args: unknown[]) => void; - - class MockWebSocket { - static readonly OPEN = 1; - static readonly CLOSED = 3; - static instances: MockWebSocket[] = []; - - readonly listeners = new Map(); - readyState = 0; - sent: string[] = []; - closed = false; - terminated = false; - deferClose = false; - deferredClose: (() => void) | undefined; - args: unknown[]; - - constructor(...args: unknown[]) { - this.args = args; - MockWebSocket.instances.push(this); - } - - on(event: string, listener: Listener): this { - const listeners = this.listeners.get(event) ?? []; - listeners.push(listener); - this.listeners.set(event, listeners); - return this; - } - - emit(event: string, ...args: unknown[]): void { - for (const listener of this.listeners.get(event) ?? []) { - listener(...args); - } - } - - send(payload: string): void { - this.sent.push(payload); - } - - close(code?: number, reason?: string): void { - this.closed = true; - this.readyState = MockWebSocket.CLOSED; - const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); - if (this.deferClose) { - this.deferredClose = emitClose; - return; - } - emitClose(); - } - - terminate(): void { - this.terminated = true; - this.close(1006, "terminated"); - } - - emitDeferredClose(): void { - const emitClose = this.deferredClose; - this.deferredClose = undefined; - emitClose?.(); - } - } - - return { - FakeWebSocket: MockWebSocket, - execFileSyncMock: vi.fn(), - fetchWithSsrFGuardMock: vi.fn(), - isProviderAuthProfileConfiguredMock: vi.fn(), - resolveProviderAuthProfileApiKeyMock: vi.fn(), - }; -}); - -vi.mock("node:child_process", async (importOriginal) => { - const actual = await importOriginal(); - return { - ...actual, - execFileSync: execFileSyncMock, - }; -}); - -vi.mock("ws", () => ({ - default: FakeWebSocket, -})); - -vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ - fetchWithSsrFGuard: fetchWithSsrFGuardMock, -})); - -vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ - isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, - resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, -})); - -type FakeWebSocketInstance = InstanceType; -type SentRealtimeEvent = { - type: string; - event_id?: string; - audio?: string; - item_id?: string; - item?: unknown; - content_index?: number; - audio_end_ms?: number; - session?: { - type?: string; - model?: string; - modalities?: string[]; - instructions?: string; - voice?: string; - input_audio_format?: string; - output_audio_format?: string; - input_audio_transcription?: Record; - turn_detection?: { - create_response?: boolean; - }; - output_modalities?: string[]; - tools?: Array<{ name?: string }>; - audio?: { - input?: { - format?: Record; - noise_reduction?: Record | null; - transcription?: Record; - turn_detection?: { - create_response?: boolean; - interrupt_response?: boolean; - }; - }; - output?: { - format?: Record; - voice?: string; - }; - }; - }; -}; - -function parseSent(socket: FakeWebSocketInstance): SentRealtimeEvent[] { - return socket.sent.map((payload: string) => JSON.parse(payload) as SentRealtimeEvent); -} - -function createNativeBridge( - overrides: Partial = {}, -): RealtimeVoiceBridge { - return buildOpenAIRealtimeVoiceProvider().createBridge({ - providerConfig: { apiKey: "sk-test" }, // pragma: allowlist secret - onAudio: vi.fn(), - onClearAudio: vi.fn(), - ...overrides, - }); -} - -function requireSocket(index = 0): FakeWebSocketInstance { - const socket = FakeWebSocket.instances[index]; - if (!socket) { - throw new Error("expected bridge to create a websocket"); - } - return socket; -} - -function beginBridgeConnection( - bridge: RealtimeVoiceBridge, - socketIndex = 0, -): { connecting: Promise; socket: FakeWebSocketInstance } { - const connecting = bridge.connect(); - return { connecting, socket: requireSocket(socketIndex) }; -} - -function openSocket(socket: FakeWebSocketInstance): void { - socket.readyState = FakeWebSocket.OPEN; - socket.emit("open"); -} - -function emitServerEvent(socket: FakeWebSocketInstance, event: Record): void { - socket.emit("message", Buffer.from(JSON.stringify(event))); -} - -function emitSessionUpdated(socket: FakeWebSocketInstance): void { - emitServerEvent(socket, { type: "session.updated" }); -} - -function emitCompletedToolCalls( - socket: FakeWebSocketInstance, - callIds: string[] = ["call_1"], -): void { - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_tools", - status: "completed", - output: callIds.map((callId, index) => ({ - id: `item_${index + 1}`, - type: "function_call", - status: "completed", - call_id: callId, - name: "lookup_weather", - arguments: "{}", - })), - }, - }); -} - -function emitFunctionOutputAdded(socket: FakeWebSocketInstance, callId: string): void { - emitServerEvent(socket, { - type: "conversation.item.added", - item: { type: "function_call_output", call_id: callId }, - }); -} - -function expectedFunctionOutput(callId: string, result: unknown) { - return expect.objectContaining({ - type: "conversation.item.create", - item: { - type: "function_call_output", - call_id: callId, - output: JSON.stringify(result), - }, - }); -} - -async function connectReadyBridge( - bridge: RealtimeVoiceBridge, - socketIndex = 0, -): Promise { - const { connecting, socket } = beginBridgeConnection(bridge, socketIndex); - openSocket(socket); - emitSessionUpdated(socket); - await connecting; - return socket; -} - -function expectedResponseCreateEvent() { - return expect.objectContaining({ - type: "response.create", - event_id: expect.stringMatching(/^openclaw-response-create-/), - }); -} - -function expectedResponseCancelEvent() { - return expect.objectContaining({ - type: "response.cancel", - event_id: expect.stringMatching(/^openclaw-response-cancel-/), - }); -} - -function createJsonResponse(body: unknown, init?: { status?: number }): Response { - return new Response(JSON.stringify(body), { - status: init?.status ?? 200, - headers: { - "Content-Type": "application/json", - }, - }); -} - -function requireRecord(value: unknown, label: string): Record { - expect(isRecord(value), `${label} must be an object`).toBe(true); - return value as Record; -} - -function requireNestedRecord( - value: unknown, - path: readonly string[], - label = path.join("."), -): Record { - let current = requireRecord(value, label); - for (const key of path) { - current = requireRecord(current[key], `${label}.${key}`); - } - return current; -} - -function expectRecordFields( - value: unknown, - label: string, - expected: Record, -): Record { - const record = requireRecord(value, label); - for (const [key, expectedValue] of Object.entries(expected)) { - expect(record[key], `${label}.${key}`).toEqual(expectedValue); - } - return record; -} - -function firstMockCall( - mock: { mock: { calls: Array } }, - label: string, -): readonly unknown[] { - const call = mock.mock.calls[0]; - if (!call) { - throw new Error(`expected ${label} call`); - } - return call; -} - -function requireFetchRequest(callIndex = 0): Record { - return requireRecord(fetchWithSsrFGuardMock.mock.calls[callIndex]?.[0], "fetch request"); -} - -function requireFetchInit(callIndex = 0): Record { - return requireRecord(requireFetchRequest(callIndex).init, "fetch init"); -} - -function requireFetchHeaders(callIndex = 0): Record { - return requireRecord(requireFetchInit(callIndex).headers, "fetch headers"); -} - -function requireFetchJsonBody(callIndex = 0): Record { - const body = requireFetchInit(callIndex).body; - expect(typeof body, "fetch body must be a JSON string").toBe("string"); - return requireRecord(JSON.parse(body as string), "fetch JSON body"); -} - -function requireSession(socket: FakeWebSocketInstance, index = 0): Record { - return requireRecord(parseSent(socket)[index]?.session, "session"); -} - -function hasSentEventType(socket: FakeWebSocketInstance, type: string): boolean { - return parseSent(socket).some((event) => event.type === type); -} - -function createRealtimeTool(name: string): RealtimeVoiceTool { - return { - type: "function", - name, - description: "Contract test tool", - parameters: { type: "object", properties: {} }, - }; -} - -function createUnreadableToolName(): RealtimeVoiceTool { - return { - type: "function", - get name(): string { - throw new Error("unreadable tool name"); - }, - description: "Contract test tool", - parameters: { type: "object", properties: {} }, - }; -} - -function createMalformedToolName(name: unknown): RealtimeVoiceTool { - return { - type: "function", - name, - description: "Contract test tool", - parameters: { type: "object", properties: {} }, - } as unknown as RealtimeVoiceTool; -} - -function createTestJwt(payload: Record): string { - return [ - Buffer.from(JSON.stringify({ alg: "none" })).toString("base64url"), - Buffer.from(JSON.stringify(payload)).toString("base64url"), - "test-signature", - ].join("."); -} - -describe("buildOpenAIRealtimeVoiceProvider", () => { - beforeEach(() => { - FakeWebSocket.instances = []; - vi.stubEnv("OPENAI_API_KEY", ""); - execFileSyncMock.mockReset(); - fetchWithSsrFGuardMock.mockReset(); - isProviderAuthProfileConfiguredMock.mockReset(); - isProviderAuthProfileConfiguredMock.mockReturnValue(false); - resolveProviderAuthProfileApiKeyMock.mockReset(); - resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); - }); - - afterEach(() => { - vi.useRealTimers(); - vi.unstubAllEnvs(); - }); - - it("declares realtime Talk capabilities for catalog selection", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - - expect(provider.defaultModel).toBe("gpt-realtime-2.1"); - expect(provider.capabilities).toEqual({ - transports: ["webrtc", "gateway-relay"], - inputAudioFormats: [ - { encoding: "g711_ulaw", sampleRateHz: 8000, channels: 1 }, - { encoding: "pcm16", sampleRateHz: 24000, channels: 1 }, - ], - outputAudioFormats: [ - { encoding: "g711_ulaw", sampleRateHz: 8000, channels: 1 }, - { encoding: "pcm16", sampleRateHz: 24000, channels: 1 }, - ], - supportsBrowserSession: true, - supportsBargeIn: true, - handlesInputAudioBargeIn: true, - supportsToolCalls: true, - supportsVideoFrames: true, - }); - }); - - it("advertises continuing realtime tool results", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - providerConfig: { apiKey: "sk-test" }, // pragma: allowlist secret - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - expect(bridge.supportsToolResultContinuation).toBe(true); - expect(bridge.supportsToolResultSuppression).toBe(true); - }); - - it("advertises quicksilver capabilities only for curated /v1/live models", () => { - const quicksilverBroker = { - capabilities: { - transports: ["webrtc" as const], - handlesAgentConsult: true as const, - supportsToolCalls: false, - supportsVideoFrames: false, - }, - createBrowserSession: vi.fn(), - cancelBrowserSession: vi.fn(), - }; - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: quicksilverBroker, - }); - const internalApi = readInternalRealtimeVoiceProviderApi(provider); - - expect( - internalApi.resolveBrowserSessionCapabilities({ - providerConfig: { model: "gpt-realtime-2.1" }, - model: "gpt-live-1-codex", - }), - ).toMatchObject({ - transports: ["webrtc", "gateway-relay"], - handlesAgentConsult: true, - supportsToolCalls: false, - supportsVideoFrames: false, - }); - expect( - internalApi.resolveGatewayRelayCapabilities({ - providerConfig: { model: "gpt-realtime-2.1" }, - model: "gpt-live-1-codex", - }), - ).toMatchObject({ - transports: ["webrtc", "gateway-relay"], - handlesAgentConsult: true, - supportsToolCalls: false, - }); - expect( - internalApi.resolveBrowserSessionCapabilities({ - providerConfig: { model: "gpt-realtime-2.1" }, - model: "gpt-live-1-mini", - }), - ).not.toHaveProperty("handlesAgentConsult"); - expect( - internalApi.resolveGatewayRelayCapabilities({ - providerConfig: { model: "gpt-realtime-2.1" }, - model: "gpt-live-1-mini", - }), - ).not.toHaveProperty("handlesAgentConsult"); - }); - - it("adds OpenClaw attribution headers to native realtime websocket requests", () => { - vi.stubEnv("OPENCLAW_VERSION", "2026.3.22"); - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - providerConfig: { apiKey: "sk-test" }, // pragma: allowlist secret - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - void bridge.connect(); - bridge.close(); - - const socket = FakeWebSocket.instances[0]; - const options = socket?.args[1] as - | { headers?: Record; maxPayload?: number } - | undefined; - expectRecordFields(options?.headers, "websocket headers", { - originator: "openclaw", - version: "2026.3.22", - "User-Agent": "openclaw/2026.3.22", - }); - expect(options?.headers).not.toHaveProperty("OpenAI-Beta"); - expect(options?.maxPayload).toBe(16 * 1024 * 1024); - }); - - it("requires Platform auth for native realtime websocket bridges", async () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { model: "gpt-realtime-2" }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - await expect(bridge.connect()).rejects.toThrow( - "OpenAI Realtime voice requires an OpenAI Platform API key", - ); - - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - expect(FakeWebSocket.instances).toHaveLength(0); - }); - - it("uses OPENAI_API_KEY for default GPT realtime bridges", async () => { - vi.stubEnv("OPENAI_API_KEY", "sk-env"); // pragma: allowlist secret - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { model: "gpt-realtime-2" }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - void bridge.connect(); - await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(1)); - bridge.close(); - - expect(resolveProviderAuthProfileApiKeyMock.mock.calls).toEqual([ - [ - { - provider: "openai", - cfg: {}, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }, - ], - ]); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - const socket = FakeWebSocket.instances[0]; - const options = socket?.args[1] as { headers?: Record } | undefined; - expect(options?.headers?.Authorization).toBe("Bearer sk-env"); - }); - - it("does not use Codex OAuth profiles for default GPT realtime bridges", async () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { model: "gpt-realtime-2" }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - await expect(bridge.connect()).rejects.toThrow( - "OpenAI Realtime voice requires an OpenAI Platform API key", - ); - - expect(resolveProviderAuthProfileApiKeyMock.mock.calls).toEqual([ - [ - { - provider: "openai", - cfg: {}, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }, - ], - ]); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - expect(FakeWebSocket.instances).toHaveLength(0); - }); - - it("uses OPENAI_API_KEY when a configured API-key profile cannot be resolved", async () => { - vi.stubEnv("OPENAI_API_KEY", "sk-env"); // pragma: allowlist secret - resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined); - isProviderAuthProfileConfiguredMock.mockReturnValueOnce(true); - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { model: "gpt-realtime-2" }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - void bridge.connect(); - await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(1)); - bridge.close(); - - expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledTimes(1); - const socket = FakeWebSocket.instances[0]; - const options = socket?.args[1] as { headers?: Record } | undefined; - expect(options?.headers?.Authorization).toBe("Bearer sk-env"); - }); - - it("uses OpenAI API-key auth profiles", async () => { - resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce("sk-profile"); // pragma: allowlist secret - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { model: "gpt-realtime-2" }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - void bridge.connect(); - await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(1)); - bridge.close(); - - expect(resolveProviderAuthProfileApiKeyMock.mock.calls).toEqual([ - [ - { - provider: "openai", - cfg: {}, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }, - ], - ]); - const socket = FakeWebSocket.instances[0]; - const options = socket?.args[1] as { headers?: Record } | undefined; - expect(options?.headers?.Authorization).toBe("Bearer sk-profile"); - }); - - it("keeps explicit OpenAI realtime API keys as the advanced override", () => { - vi.stubEnv("OPENAI_API_KEY", "sk-env"); // pragma: allowlist secret - resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce("sk-profile"); // pragma: allowlist secret - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { - apiKey: "sk-configured", // pragma: allowlist secret - model: "gpt-realtime-2", - }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - void bridge.connect(); - bridge.close(); - - expect(resolveProviderAuthProfileApiKeyMock).not.toHaveBeenCalled(); - const socket = FakeWebSocket.instances[0]; - const options = socket?.args[1] as { headers?: Record } | undefined; - expect(options?.headers?.Authorization).toBe("Bearer sk-configured"); - }); - - it("requires an API key for custom realtime endpoints", async () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: { - azureEndpoint: "https://example.openai.azure.com", - model: "gpt-realtime-2", - }, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - await expect(bridge.connect()).rejects.toThrow("OpenAI Realtime voice requires an API key"); - - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - expect(FakeWebSocket.instances).toHaveLength(0); - }); - - it("returns browser-safe OpenClaw attribution headers for native WebRTC offers", async () => { - vi.stubEnv("OPENCLAW_VERSION", "2026.3.22"); - fetchWithSsrFGuardMock.mockResolvedValueOnce({ - response: createJsonResponse({ - client_secret: { value: "client-secret-123" }, - expires_at: 1_765_000_000, - }), - release: vi.fn(async () => undefined), - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - if (!provider.createBrowserSession) { - throw new Error("expected OpenAI realtime provider to support browser sessions"); - } - - const session = await provider.createBrowserSession({ - providerConfig: { apiKey: "sk-test" }, // pragma: allowlist secret - instructions: "Be concise.", - voice: " Marin ", - }); - - expectRecordFields(requireFetchRequest(), "fetch request", { - url: "https://api.openai.com/v1/realtime/client_secrets", - policy: { - allowRfc2544BenchmarkRange: true, - allowIpv6UniqueLocalRange: true, - hostnameAllowlist: ["api.openai.com"], - }, - }); - expectRecordFields(requireFetchInit(), "fetch init", { method: "POST" }); - expectRecordFields(requireFetchHeaders(), "fetch headers", { - Authorization: "Bearer sk-test", // pragma: allowlist secret - "Content-Type": "application/json", - originator: "openclaw", - version: "2026.3.22", - "User-Agent": "openclaw/2026.3.22", - }); - const body = requireFetchJsonBody(); - const bodySession = requireRecord(body.session, "fetch session"); - expect(bodySession.model).toBe("gpt-realtime-2.1"); - expect(requireNestedRecord(bodySession, ["audio", "input"])).toEqual({ - noise_reduction: { type: "near_field" }, - turn_detection: { - type: "server_vad", - create_response: true, - interrupt_response: true, - }, - transcription: { model: "gpt-4o-mini-transcribe" }, - }); - expect(requireNestedRecord(bodySession, ["audio", "output"])).toEqual({ voice: "marin" }); - expect(bodySession).not.toHaveProperty("temperature"); - expectRecordFields(session, "browser session", { - provider: "openai", - transport: "webrtc", - clientSecret: "client-secret-123", - offerUrl: "https://api.openai.com/v1/realtime/calls", - model: "gpt-realtime-2.1", - expiresAt: 1_765_000_000_000, - }); - // originator, version, and User-Agent are server-side attribution headers; they - // must not be forwarded to the browser so that the browser's direct SDP POST to - // api.openai.com passes the CORS preflight (only authorization,content-type - // allowed — #76435). All three are filtered, leaving no browser offer headers. - expect((session as { offerHeaders?: Record }).offerHeaders).toBeUndefined(); - }); - - it.each(["configured", "profile", "environment"] as const)( - "explains how auth precedence affects a rejected %s API key", - async (source) => { - if (source === "profile") { - resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce("sk-profile"); // pragma: allowlist secret - } else if (source === "environment") { - vi.stubEnv("OPENAI_API_KEY", "sk-env"); // pragma: allowlist secret - } - fetchWithSsrFGuardMock.mockResolvedValueOnce({ - response: createJsonResponse( - { error: { message: "Incorrect API key provided: sk-proj-***" } }, - { status: 401 }, - ), - release: vi.fn(async () => undefined), - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - if (!provider.createBrowserSession) { - throw new Error("expected OpenAI realtime provider to support browser sessions"); - } - - await expect( - provider.createBrowserSession({ - providerConfig: - source === "configured" - ? { apiKey: "sk-stale" } // pragma: allowlist secret - : {}, - }), - ).rejects.toThrow( - "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source", - ); - }, - ); - - it("omits unsupported OpenAI tool names from browser sessions", async () => { - fetchWithSsrFGuardMock.mockResolvedValueOnce({ - response: createJsonResponse({ client_secret: { value: "client-secret-123" } }), - release: vi.fn(async () => undefined), - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - if (!provider.createBrowserSession) { - throw new Error("expected OpenAI realtime provider to support browser sessions"); - } - - await provider.createBrowserSession({ - providerConfig: { apiKey: "sk-test" }, // pragma: allowlist secret - tools: [ - createRealtimeTool("1_lookup"), - createRealtimeTool("calendar.lookup:next"), - createMalformedToolName(undefined), - createUnreadableToolName(), - ], - }); - - const bodySession = requireRecord(requireFetchJsonBody().session, "fetch session"); - const tools = bodySession.tools as Array<{ name?: string }>; - expect(tools.map((tool) => tool.name)).toEqual(["1_lookup"]); - }); - - it("resolves keychain OPENAI_API_KEY refs before creating browser sessions", async () => { - vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_BROWSER_TEST"); - execFileSyncMock.mockReturnValueOnce("sk-browser-env\n"); // pragma: allowlist secret - fetchWithSsrFGuardMock.mockResolvedValueOnce({ - response: createJsonResponse({ - client_secret: { value: "client-secret-123" }, - }), - release: vi.fn(async () => undefined), - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - if (!provider.createBrowserSession) { - throw new Error("expected OpenAI realtime provider to support browser sessions"); - } - - await provider.createBrowserSession({ - providerConfig: {}, - instructions: "Be concise.", - }); - - const [securityBinary, securityArgs, securityOptions] = firstMockCall( - execFileSyncMock, - "security keychain lookup", - ); - expect(securityBinary).toBe("/usr/bin/security"); - expect(securityArgs).toEqual([ - "find-generic-password", - "-s", - "openclaw", - "-a", - "OPENAI_REALTIME_BROWSER_TEST", - "-w", - ]); - expectRecordFields(securityOptions, "security command options", { - encoding: "utf8", - timeout: 5000, - }); - expectRecordFields(requireFetchHeaders(), "fetch headers", { - Authorization: "Bearer sk-browser-env", // pragma: allowlist secret - }); - }); - - it("resolves and caches keychain OPENAI_API_KEY refs before creating bridges", async () => { - vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_BRIDGE_TEST"); - execFileSyncMock.mockReturnValue("sk-bridge-env\n"); // pragma: allowlist secret - const provider = buildOpenAIRealtimeVoiceProvider(); - - const first = provider.createBridge({ - providerConfig: {}, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - const second = provider.createBridge({ - providerConfig: {}, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - void first.connect(); - void second.connect(); - await vi.waitFor(() => expect(FakeWebSocket.instances.length).toBe(2)); - first.close(); - second.close(); - - expect(execFileSyncMock).toHaveBeenCalledTimes(1); - for (const socket of FakeWebSocket.instances) { - const options = socket.args[1] as { headers?: Record } | undefined; - expectRecordFields(options?.headers, "websocket headers", { - Authorization: "Bearer sk-bridge-env", // pragma: allowlist secret - }); - } - }); - - it("does not resolve keychain refs during configured checks", () => { - vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_CONFIGURED_TEST"); - const provider = buildOpenAIRealtimeVoiceProvider(); - - expect(provider.isConfigured({ providerConfig: {} })).toBe(true); - expect(execFileSyncMock).not.toHaveBeenCalled(); - }); - - it("does not treat Codex OAuth profiles as configured for realtime sessions", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const cfg = { agents: { defaults: {} } } as never; - - expect(provider.isConfigured({ cfg, providerConfig: {} })).toBe(false); - expect(isProviderAuthProfileConfiguredMock).toHaveBeenCalledWith({ - provider: "openai", - cfg, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }); - }); - - it("routes gpt-live Platform sessions through the native quicksilver broker", async () => { - const createBrowserSession = vi.fn(async (_request: unknown, _auth: unknown) => ({ - provider: "openai", - transport: "webrtc" as const, - clientSecret: "quicksilver-token", - offerUrl: "/plugins/openai/realtime/calls", - })); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { - transports: ["webrtc" as const], - handlesAgentConsult: true as const, - supportsToolCalls: false, - supportsVideoFrames: false, - }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - const request = { - providerConfig: { apiKey: "sk-platform" }, // pragma: allowlist secret - model: "gpt-live-1", - agentId: "main", - workspaceDir: "/tmp/openclaw-agent-workspace", - initialItems: [], - runAgentConsult: vi.fn(async () => ({ text: "Done" })), - }; - - await expect(provider.createBrowserSession?.(request)).resolves.toMatchObject({ - offerUrl: "/plugins/openai/realtime/calls", - }); - expect(createBrowserSession).toHaveBeenCalledWith(expect.objectContaining(request), { - type: "api-key", - token: "sk-platform", // pragma: allowlist secret - }); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - }); - - it("routes an explicit unlisted gpt-live alias without advertising it as ready", async () => { - const oauthToken = createTestJwt({ - "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, - }); - resolveProviderAuthProfileApiKeyMock.mockImplementation( - async ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") ? oauthToken : undefined, - ); - isProviderAuthProfileConfiguredMock.mockImplementation( - ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") === true, - ); - const createBrowserSession = vi.fn(async () => ({ - provider: "openai", - transport: "webrtc" as const, - clientSecret: "quicksilver-token", - offerUrl: "/plugins/openai/realtime/calls", - })); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { - transports: ["webrtc" as const], - handlesAgentConsult: true as const, - supportsToolCalls: false, - supportsVideoFrames: false, - }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - const cfg = { agents: { defaults: {} } } as never; - const request = { - cfg, - providerConfig: {}, - model: "gpt-live-1-mini", - agentId: "main", - workspaceDir: "/tmp/openclaw-agent-workspace", - initialItems: [], - runAgentConsult: vi.fn(async () => ({ text: "Done" })), - }; - - expect(provider.isConfigured({ cfg, providerConfig: { model: "gpt-live-1-mini" } })).toBe( - false, - ); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-mini" }, - agentId: "main", - }), - ).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { - model: "gpt-live-1-mini", - azureEndpoint: "https://example.openai.azure.com", - azureDeployment: "gpt-live", - }, - agentId: "main", - }), - ).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-mini" }, - agentId: "main", - }), - ).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { model: "gpt-realtime-2.1", apiKey: "sk-platform" }, - agentId: "main", - }), - ).toBeUndefined(); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { - model: "gpt-realtime-2.1", - apiKey: "sk-platform", - azureEndpoint: "https://example.openai.azure.com", - }, - agentId: "main", - }), - ).toBeUndefined(); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { - model: "gpt-live-1-codex", - apiKey: "sk-platform", - azureEndpoint: "https://example.openai.azure.com", - }, - agentId: "main", - }), - ).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-mini", apiKey: "sk-platform" }, - agentId: "main", - }), - ).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-mini", apiKey: "sk-platform" }, - agentId: "main", - }), - ).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-codex" }, - agentId: "main", - }), - ).toBe(true); - expect( - readInternalRealtimeVoiceProviderApi(provider).isGatewayRelayConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-codex" }, - agentId: "voice-agent", - }), - ).toBe(true); - expect(isProviderAuthProfileConfiguredMock).toHaveBeenCalledWith( - expect.objectContaining({ - agentDir: expect.stringContaining("voice-agent"), - profileTypes: ["oauth"], - }), - ); - expect( - readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ - cfg, - providerConfig: { model: "gpt-live-1-codex" }, - agentId: "main", - }), - ).toBe(true); - await provider.createBrowserSession?.(request); - expect(createBrowserSession).toHaveBeenCalledWith(expect.objectContaining(request), { - type: "oauth", - token: oauthToken, - accountId: "account-123", - }); - expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledWith( - expect.objectContaining({ - provider: "openai", - profileTypes: ["oauth"], - includeExternalCliAuth: false, - }), - ); - }); - - it("rejects forced consult routing for prefix-routed gpt-live sessions", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const internalApi = readInternalRealtimeVoiceProviderApi(provider); - - expect( - internalApi.validateGatewayRelayLaunch({ - providerConfig: { model: "gpt-live-future-alias" }, - autoRespondToAudio: false, - }), - ).toContain("cannot use forced agent consult routing"); - expect( - internalApi.validateGatewayRelayLaunch({ - providerConfig: { model: "gpt-realtime-2.1" }, - autoRespondToAudio: false, - }), - ).toBeUndefined(); - }); - - it("prefers ChatGPT OAuth over Platform auth for gpt-live", async () => { - const oauthToken = createTestJwt({ - "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, - }); - resolveProviderAuthProfileApiKeyMock.mockImplementation( - async ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") ? oauthToken : undefined, - ); - const createBrowserSession = vi.fn(async () => ({ - provider: "openai", - transport: "webrtc" as const, - clientSecret: "quicksilver-token", - offerUrl: "/plugins/openai/realtime/calls", - })); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { handlesAgentConsult: true as const }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - - await provider.createBrowserSession?.({ - providerConfig: { apiKey: "sk-platform" }, // pragma: allowlist secret - model: "gpt-live-1-codex", - agentId: "main", - workspaceDir: "/tmp/openclaw-agent-workspace", - initialItems: [], - runAgentConsult: vi.fn(async () => ({ text: "Done" })), - } as never); - - expect(createBrowserSession).toHaveBeenCalledWith(expect.any(Object), { - type: "oauth", - token: oauthToken, - accountId: "account-123", - }); - }); - - it("keeps Platform precedence for GA realtime when OAuth is also available", async () => { - const oauthToken = createTestJwt({ - "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, - }); - resolveProviderAuthProfileApiKeyMock.mockImplementation( - async ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") ? oauthToken : undefined, - ); - fetchWithSsrFGuardMock.mockResolvedValueOnce({ - response: createJsonResponse({ client_secret: { value: "client-secret-123" } }), - release: vi.fn(async () => undefined), - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - - await provider.createBrowserSession?.({ - providerConfig: { apiKey: "sk-platform" }, // pragma: allowlist secret - model: "gpt-realtime-2.1", - }); - - expect(resolveProviderAuthProfileApiKeyMock).not.toHaveBeenCalledWith( - expect.objectContaining({ profileTypes: ["oauth"] }), - ); - expectRecordFields(requireFetchHeaders(), "fetch headers", { - Authorization: "Bearer sk-platform", // pragma: allowlist secret - }); - }); - - it("sends one shared GA policy and waits for session.updated on an attached sideband", async () => { - const createBrowserSession = vi.fn( - async (_request: unknown, _auth: unknown) => - ({ - provider: "openai", - transport: "webrtc" as const, - clientSecret: "gateway-token", - offerUrl: "/plugins/openai/realtime/calls", - }) as const, - ); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { handlesAgentConsult: true as const }, - createBrowserSession, - cancelBrowserSession: vi.fn(async () => undefined), - }, - }); - const bindBridge = vi.fn(); - const onEvent = vi.fn(); - const onReady = vi.fn(); - const cfg = {} as never; - - expect( - readInternalRealtimeVoiceProviderApi(provider).resolveBrowserSessionCapabilities({ - cfg, - providerConfig: { apiKey: "sk-platform" }, // pragma: allowlist secret - model: "gpt-realtime-2.1", - }), - ).toMatchObject({ supportsGatewayControl: true }); - await expect( - provider.createBrowserSession?.({ - cfg, - providerConfig: { apiKey: "sk-platform" }, // pragma: allowlist secret - instructions: "Stay concise.", - model: "gpt-realtime-2.1", - prefixPaddingMs: 420, - reasoningEffort: "medium", - silenceDurationMs: 650, - tools: [createRealtimeTool("openclaw_agent_consult")], - vadThreshold: 0.7, - voice: "marin", - gatewayControl: { bindBridge, onEvent, onReady }, - }), - ).resolves.toMatchObject({ - clientSecret: "gateway-token", - offerUrl: "/plugins/openai/realtime/calls", - }); - const brokerRequest = requireRecord(createBrowserSession.mock.calls[0]?.[0], "broker request"); - expect(createBrowserSession.mock.calls[0]?.[1]).toEqual({ - type: "api-key", - token: "sk-platform", // pragma: allowlist secret - }); - const gaSideband = requireRecord(brokerRequest.gaSideband, "GA sideband request"); - expect(gaSideband.session).toMatchObject({ - type: "realtime", - instructions: "Stay concise.", - model: "gpt-realtime-2.1", - output_modalities: ["audio"], - reasoning: { effort: "medium" }, - tool_choice: "auto", - audio: { - input: { - format: { type: "audio/pcm", rate: 24000 }, - noise_reduction: { type: "near_field" }, - turn_detection: { - type: "server_vad", - threshold: 0.7, - prefix_padding_ms: 420, - silence_duration_ms: 650, - create_response: true, - interrupt_response: true, - }, - }, - output: { format: { type: "audio/pcm", rate: 24000 }, voice: "marin" }, - }, - }); - const createBridge = gaSideband.createBridge as (params: { - apiKey: string; - callId: string; - onTerminal: () => void; - }) => RealtimeVoiceBridge; - const bridge = createBridge({ - apiKey: "sk-platform", // pragma: allowlist secret - callId: "rtc_gateway", - onTerminal: vi.fn(), - }); - expect(bindBridge).toHaveBeenCalledWith(bridge); - const { connecting, socket } = beginBridgeConnection(bridge); - let connectResolved = false; - void connecting.then(() => { - connectResolved = true; - }); - expect(socket.args[0]).toBe("wss://api.openai.com/v1/realtime?call_id=rtc_gateway"); - openSocket(socket); - await Promise.resolve(); - const sessionUpdates = parseSent(socket).filter((event) => event.type === "session.update"); - expect(sessionUpdates).toHaveLength(1); - expect(sessionUpdates[0]?.session).toEqual(gaSideband.session); - emitServerEvent(socket, { - type: "session.created", - session: { type: "realtime", tools: [{ type: "function" }], tool_choice: "auto" }, - }); - await Promise.resolve(); - expect(connectResolved).toBe(false); - expect(onReady).not.toHaveBeenCalled(); - expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength(1); - emitSessionUpdated(socket); - await connecting; - expect(connectResolved).toBe(true); - expect(onReady).toHaveBeenCalledOnce(); - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "session.created", - detail: "tools=1 toolChoice=auto", - }); - bridge.close(); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - }); - - it("does not advertise GA Gateway control for OAuth-only browser auth", () => { - isProviderAuthProfileConfiguredMock.mockImplementation( - ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") === true, - ); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { handlesAgentConsult: true as const }, - createBrowserSession: vi.fn(), - cancelBrowserSession: vi.fn(async () => undefined), - }, - }); - expect( - readInternalRealtimeVoiceProviderApi(provider).resolveBrowserSessionCapabilities({ - cfg: {}, - providerConfig: {}, - model: "gpt-realtime-2.1", - }), - ).not.toHaveProperty("supportsGatewayControl"); - }); - - it("uses ChatGPT OAuth as the browser-only fallback for GA realtime", async () => { - const oauthToken = createTestJwt({ - "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, - }); - resolveProviderAuthProfileApiKeyMock.mockImplementation( - async ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") ? oauthToken : undefined, - ); - isProviderAuthProfileConfiguredMock.mockImplementation( - ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") === true, - ); - const createBrowserSession = vi.fn(async () => ({ - provider: "openai", - transport: "webrtc" as const, - clientSecret: "broker-token", - offerUrl: "/plugins/openai/realtime/calls", - })); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { handlesAgentConsult: true as const }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - const cfg = { agents: { defaults: {} } } as never; - const request = { - cfg, - providerConfig: {}, - model: "gpt-realtime-2.1", - voice: "cedar", - agentId: "main", - workspaceDir: "/tmp/openclaw-agent-workspace", - initialItems: [], - }; - - expect(provider.isConfigured({ cfg, providerConfig: {} })).toBe(false); - expect( - readInternalRealtimeVoiceProviderApi(provider).isBrowserSessionConfigured({ - cfg, - providerConfig: { model: "gpt-realtime-2.1" }, - agentId: "main", - }), - ).toBe(true); - await expect(provider.createBrowserSession?.(request)).resolves.toMatchObject({ - clientSecret: "broker-token", - offerUrl: "/plugins/openai/realtime/calls", - }); - expect(createBrowserSession).toHaveBeenCalledWith( - expect.objectContaining({ model: "gpt-realtime-2.1", voice: "cedar" }), - { type: "oauth", token: oauthToken, accountId: "account-123" }, - ); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - }); - - it("does not use GA OAuth fallback when a Platform credential source is unresolved", async () => { - const oauthToken = createTestJwt({ - "https://api.openai.com/auth": { chatgpt_account_id: "account-123" }, - }); - resolveProviderAuthProfileApiKeyMock.mockImplementation( - async ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("oauth") ? oauthToken : undefined, - ); - isProviderAuthProfileConfiguredMock.mockImplementation( - ({ profileTypes }: { profileTypes?: readonly string[] }) => - profileTypes?.includes("api_key") === true, - ); - const createBrowserSession = vi.fn(); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { handlesAgentConsult: true as const }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - - await expect( - provider.createBrowserSession?.({ - cfg: {} as never, - providerConfig: {}, - model: "gpt-realtime-2.1", - agentId: "main", - workspaceDir: "/tmp/openclaw-agent-workspace", - initialItems: [], - } as never), - ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); - expect(createBrowserSession).not.toHaveBeenCalled(); - expect(resolveProviderAuthProfileApiKeyMock).not.toHaveBeenCalledWith( - expect.objectContaining({ profileTypes: ["oauth"] }), - ); - }); - - it("passes configured gpt-live model and voice to the native broker", async () => { - const createBrowserSession = vi.fn(async (_request: unknown, _auth: unknown) => ({ - provider: "openai", - transport: "webrtc" as const, - clientSecret: "quicksilver-token", - offerUrl: "/plugins/openai/realtime/calls", - })); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { - transports: ["webrtc" as const], - handlesAgentConsult: true as const, - supportsToolCalls: false, - supportsVideoFrames: false, - }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - - await provider.createBrowserSession?.({ - providerConfig: { - apiKey: "sk-platform", // pragma: allowlist secret - model: "gpt-live-1", - speakerVoice: "cedar", - }, - instructions: "Always address the caller as Captain.", - agentId: "voice-agent", - workspaceDir: "/tmp/openclaw-agent-workspace", - initialItems: [], - runAgentConsult: vi.fn(async () => ({ text: "Done" })), - } as never); - - expect(createBrowserSession).toHaveBeenCalledWith( - expect.objectContaining({ model: "gpt-live-1", voice: "cedar" }), - { type: "api-key", token: "sk-platform" }, // pragma: allowlist secret - ); - const quicksilverRequest = requireRecord( - createBrowserSession.mock.calls[0]?.[0], - "quicksilver request", - ); - expect(quicksilverRequest.instructions).toMatch(/^You are OpenClaw's realtime voice layer\./); - expect(quicksilverRequest.instructions).toContain( - "Context on the commentary channel is silent background", - ); - expect(quicksilverRequest.instructions).toContain( - "Context on the speakable channel is your answer", - ); - expect(quicksilverRequest.instructions).toMatch(/Always address the caller as Captain\.$/); - }); - - it("explains both gpt-live authentication options when neither is available", async () => { - const createBrowserSession = vi.fn(); - const provider = buildOpenAIRealtimeVoiceProvider({ - quicksilverBrowserSessionBroker: { - capabilities: { - transports: ["webrtc" as const], - handlesAgentConsult: true as const, - supportsToolCalls: false, - supportsVideoFrames: false, - }, - createBrowserSession, - cancelBrowserSession: vi.fn(), - }, - }); - - await expect( - provider.createBrowserSession?.({ - providerConfig: {}, - model: "gpt-live-1", - }), - ).rejects.toThrow( - "GPT-Live Talk requires either an OpenAI Platform API key or a ChatGPT OAuth subscription profile", - ); - expect(createBrowserSession).not.toHaveBeenCalled(); - }); - - it("requires Platform auth for browser sessions", async () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - await expect( - provider.createBrowserSession?.({ - providerConfig: {}, - }), - ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - }); - - it("reports an unresolved Platform credential without trying another auth route", async () => { - vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_MISSING_TEST"); - execFileSyncMock.mockImplementationOnce(() => { - throw new Error("keychain unavailable"); - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - - await expect( - provider.createBrowserSession?.({ - providerConfig: {}, - }), - ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); - }); - - it("treats OpenAI API-key auth profiles as configured for browser realtime sessions", () => { - isProviderAuthProfileConfiguredMock.mockReturnValue(true); - const provider = buildOpenAIRealtimeVoiceProvider(); - const cfg = { agents: { defaults: {} } } as never; - - expect(provider.isConfigured({ cfg, providerConfig: {} })).toBe(true); - expect(isProviderAuthProfileConfiguredMock).toHaveBeenCalledWith({ - provider: "openai", - cfg, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }); - }); - - it("does not configure Azure realtime sessions without a Platform API key", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const cfg = { agents: { defaults: {} } } as never; - - expect( - provider.isConfigured({ - cfg, - providerConfig: { - azureEndpoint: "https://example.openai.azure.com", - azureDeployment: "realtime", - }, - }), - ).toBe(false); - }); - - it("requires Platform auth before minting browser realtime client secrets", async () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - if (!provider.createBrowserSession) { - throw new Error("expected OpenAI realtime provider to support browser sessions"); - } - const cfg = { agents: { defaults: {} } } as never; - - await expect( - provider.createBrowserSession({ - cfg, - providerConfig: {}, - instructions: "Be concise.", - }), - ).rejects.toThrow("OpenAI Realtime voice requires an OpenAI Platform API key"); - expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled(); - }); - - it("uses OPENAI_API_KEY for default GPT browser sessions", async () => { - vi.stubEnv("OPENAI_API_KEY", "sk-env"); // pragma: allowlist secret - fetchWithSsrFGuardMock.mockResolvedValueOnce({ - response: createJsonResponse({ - client_secret: { value: "client-secret-123" }, - }), - release: vi.fn(async () => undefined), - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - if (!provider.createBrowserSession) { - throw new Error("expected OpenAI realtime provider to support browser sessions"); - } - const cfg = { agents: { defaults: {} } } as never; - - await provider.createBrowserSession({ - cfg, - providerConfig: {}, - model: "gpt-realtime-2", - instructions: "Be concise.", - }); - - expectRecordFields(requireFetchHeaders(), "fetch headers", { - Authorization: "Bearer sk-env", // pragma: allowlist secret - }); - }); - - it("fails closed when keychain refs cannot be resolved", async () => { - vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_MISSING_TEST"); - resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined); - execFileSyncMock.mockImplementationOnce(() => { - throw new Error("keychain unavailable"); - }); - const provider = buildOpenAIRealtimeVoiceProvider(); - - const bridge = provider.createBridge({ - providerConfig: {}, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - await expect(bridge.connect()).rejects.toThrow( - "OpenAI Realtime voice requires an OpenAI Platform API key", - ); - expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledTimes(1); - }); - - it("fails closed when a configured API-key profile cannot be resolved", async () => { - resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined); - isProviderAuthProfileConfiguredMock.mockReturnValueOnce(true); - const provider = buildOpenAIRealtimeVoiceProvider(); - const bridge = provider.createBridge({ - cfg: {} as never, - providerConfig: {}, - onAudio: vi.fn(), - onClearAudio: vi.fn(), - }); - - await expect(bridge.connect()).rejects.toThrow( - "OpenAI Realtime voice requires an OpenAI Platform API key", - ); - expect(resolveProviderAuthProfileApiKeyMock).toHaveBeenCalledTimes(1); - }); - - it("normalizes provider-owned voice settings from raw provider config", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const resolved = provider.resolveConfig?.({ - cfg: {} as never, - rawConfig: { - providers: { - openai: { - model: "gpt-realtime-2", - voice: " Verse ", - temperature: 0.6, - silenceDurationMs: 850, - vadThreshold: 0.35, - reasoningEffort: "low", - }, - }, - }, - }); - - expect(resolved).toEqual({ - model: "gpt-realtime-2", - voice: "verse", - temperature: 0.6, - silenceDurationMs: 850, - vadThreshold: 0.35, - reasoningEffort: "low", - }); - }); - - it("drops malformed realtime voice numeric settings", () => { - const provider = buildOpenAIRealtimeVoiceProvider(); - const resolved = provider.resolveConfig?.({ - cfg: {} as never, - rawConfig: { - providers: { - openai: { - vadThreshold: 1.5, - silenceDurationMs: -1, - prefixPaddingMs: 10.5, - minBargeInAudioEndMs: 25.5, - }, - }, - }, - }); - - expect(resolved?.vadThreshold).toBeUndefined(); - expect(resolved?.silenceDurationMs).toBeUndefined(); - expect(resolved?.prefixPaddingMs).toBeUndefined(); - expect(resolved?.minBargeInAudioEndMs).toBeUndefined(); - }); - - it("waits for session.updated before draining audio and firing onReady", async () => { - const onReady = vi.fn(); - const bridge = createNativeBridge({ - instructions: "Be helpful.", - language: "de", - onReady, - }); - const { connecting, socket } = beginBridgeConnection(bridge); - let connectResolved = false; - void connecting.then(() => { - connectResolved = true; - }); - - openSocket(socket); - await Promise.resolve(); - - bridge.sendAudio(Buffer.from("before-ready")); - emitServerEvent(socket, { type: "session.created" }); - - expect(connectResolved).toBe(false); - expect(onReady).not.toHaveBeenCalled(); - expect(parseSent(socket).map((event) => event.type)).toEqual(["session.update"]); - const session = requireSession(socket); - expectRecordFields(session, "session", { - type: "realtime", - model: "gpt-realtime-2.1", - output_modalities: ["audio"], - }); - const inputAudio = requireNestedRecord(session, ["audio", "input"]); - expectRecordFields(inputAudio, "session audio input", { - format: { type: "audio/pcmu" }, - noise_reduction: null, - transcription: { model: "gpt-4o-mini-transcribe", language: "de" }, - }); - expect(requireNestedRecord(session, ["audio", "output"])).toEqual({ - format: { type: "audio/pcmu" }, - voice: "alloy", - }); - expect(session).not.toHaveProperty("temperature"); - expect(bridge.isConnected()).toBe(false); - - emitSessionUpdated(socket); - await connecting; - - expect(connectResolved).toBe(true); - expect(onReady).toHaveBeenCalledTimes(1); - expect(parseSent(socket).map((event) => event.type)).toEqual([ - "session.update", - "input_audio_buffer.append", - ]); - expect(bridge.isConnected()).toBe(true); - }); - - it("bounds queued audio by aggregate bytes before session readiness", async () => { - const bridge = createNativeBridge(); - const { connecting, socket } = beginBridgeConnection(bridge); - openSocket(socket); - await Promise.resolve(); - - bridge.sendAudio(Buffer.alloc(512 * 1024, 0x01)); - bridge.sendAudio(Buffer.alloc(512 * 1024, 0x02)); - bridge.sendAudio(Buffer.from("overflow")); - emitSessionUpdated(socket); - await connecting; - - const audioEvents = parseSent(socket).filter( - (event) => event.type === "input_audio_buffer.append", - ); - expect(audioEvents).toHaveLength(2); - expect( - audioEvents.map((event) => Buffer.from(String(event.audio), "base64").byteLength), - ).toEqual([512 * 1024, 512 * 1024]); - bridge.close(); - }); - - it("discards audio closed before the first connection and reconnects fresh", async () => { - const onClose = vi.fn(); - const bridge = createNativeBridge({ onClose }); - - bridge.sendAudio(Buffer.from("queued-before-connect")); - bridge.close(); - bridge.close(); - bridge.sendAudio(Buffer.from("sent-after-close")); - - expect(FakeWebSocket.instances).toHaveLength(0); - expect(onClose).not.toHaveBeenCalled(); - - const { connecting, socket } = beginBridgeConnection(bridge); - openSocket(socket); - emitSessionUpdated(socket); - await connecting; - - expect( - parseSent(socket).filter((event) => event.type === "input_audio_buffer.append"), - ).toHaveLength(0); - - bridge.close(); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("completed"); - }); - - it("does not carry queued audio across terminal close and explicit reconnect", async () => { - const bridge = createNativeBridge(); - const { connecting: firstConnect, socket: firstSocket } = beginBridgeConnection(bridge); - openSocket(firstSocket); - await Promise.resolve(); - - bridge.sendAudio(Buffer.from("queued-before-close")); - bridge.close(); - await firstConnect; - bridge.sendAudio(Buffer.from("sent-after-close")); - - const { connecting: reconnecting, socket: secondSocket } = beginBridgeConnection(bridge, 1); - openSocket(secondSocket); - emitSessionUpdated(secondSocket); - await reconnecting; - - expect( - parseSent(secondSocket).filter((event) => event.type === "input_audio_buffer.append"), - ).toHaveLength(0); - bridge.close(); - }); - - it("shares an in-flight connection until session readiness", async () => { - const onReady = vi.fn(); - const bridge = createNativeBridge({ onReady }); - const firstConnect = bridge.connect(); - const secondConnect = bridge.connect(); - const socket = requireSocket(); - - expect(FakeWebSocket.instances).toHaveLength(1); - openSocket(socket); - emitSessionUpdated(socket); - - await Promise.all([firstConnect, secondConnect]); - expect(onReady).toHaveBeenCalledOnce(); - bridge.close(); - }); - - it("fails terminally when the readiness callback throws", async () => { - vi.useFakeTimers(); - const readyError = new Error("readiness callback failed"); - const onClose = vi.fn(); - const onError = vi.fn(); - const onReady = vi.fn(() => { - throw readyError; - }); - const bridge = createNativeBridge({ onClose, onError, onReady }); - const { connecting, socket } = beginBridgeConnection(bridge); - let connectError: unknown; - const observedConnect = connecting.catch((error: unknown) => { - connectError = error; - }); - - openSocket(socket); - bridge.sendAudio(Buffer.from("queued-before-ready")); - emitSessionUpdated(socket); - await vi.advanceTimersByTimeAsync(0); - const immediateConnectError = connectError; - - bridge.close(); - await observedConnect; - - expect(immediateConnectError).toBe(readyError); - expect(onReady).toHaveBeenCalledOnce(); - expect(onError).toHaveBeenCalledOnce(); - expect(onError).toHaveBeenCalledWith(readyError); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("error"); - expect(socket.closed).toBe(true); - expect(bridge.isConnected()).toBe(false); - expect( - parseSent(socket).filter((event) => event.type === "input_audio_buffer.append"), - ).toHaveLength(0); - - emitSessionUpdated(socket); - await expect(bridge.connect()).rejects.toBe(readyError); - expect(FakeWebSocket.instances).toHaveLength(1); - expect(onReady).toHaveBeenCalledOnce(); - expect(onError).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledOnce(); - }); - - it("suppresses auto responses before draining queued initial greeting audio", async () => { - const bridgeRef: { current?: RealtimeVoiceBridge } = {}; - const onReady = vi.fn(() => { - bridgeRef.current?.triggerGreeting?.("Say exactly: hello from explicit speech."); - }); - const bridge = createNativeBridge({ - instructions: "Be helpful.", - onReady, - }); - bridgeRef.current = bridge; - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - await Promise.resolve(); - - bridge.sendAudio(Buffer.from("before-ready")); - emitSessionUpdated(socket); - await connecting; - - const sent = parseSent(socket); - expect(sent.map((event) => event.type)).toEqual([ - "session.update", - "conversation.item.create", - "session.update", - "response.create", - "input_audio_buffer.append", - ]); - expect(sent[2]).toEqual({ - type: "session.update", - session: { - type: "realtime", - audio: { - input: { - turn_detection: { - type: "server_vad", - threshold: 0.5, - prefix_padding_ms: 300, - silence_duration_ms: 500, - create_response: false, - interrupt_response: true, - }, - }, - }, - }, - }); - expect(sent[4]).toEqual({ - type: "input_audio_buffer.append", - audio: Buffer.from("before-ready").toString("base64"), - }); - expect(sent.filter((event) => event.type === "response.create")).toHaveLength(1); - expect(onReady).toHaveBeenCalledTimes(1); - - emitServerEvent(socket, { type: "response.done" }); - - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); - - it("omits unsupported OpenAI tool names from GA session updates", async () => { - const bridge = createNativeBridge({ - tools: [ - createRealtimeTool("1_lookup"), - createRealtimeTool("calendar.lookup:next"), - createRealtimeTool("bad/name"), - createRealtimeTool("x".repeat(65)), - createMalformedToolName(null), - createMalformedToolName(42), - createUnreadableToolName(), - ], - }); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - - const tools = requireSession(socket).tools as Array<{ name?: string }>; - expect(tools.map((tool) => tool.name)).toEqual(["1_lookup", "x".repeat(65)]); - emitSessionUpdated(socket); - await connecting; - }); - - it("rotates realtime bridges on provider max-duration events without reporting an error", async () => { - vi.useFakeTimers(); - const onError = vi.fn(); - const onEvent = vi.fn(); - const onReady = vi.fn(); - const bridge = createNativeBridge({ onError, onEvent, onReady }); - const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); - - openSocket(firstSocket); - emitSessionUpdated(firstSocket); - await connecting; - expect(onReady).toHaveBeenCalledOnce(); - - firstSocket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { message: "Your session hit the maximum duration of 60 minutes." }, - }), - ), - ); - - expect(onError).not.toHaveBeenCalled(); - expect(firstSocket.closed).toBe(true); - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "session.rotation", - detail: "reason=max-duration", - }); - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "session.reconnect.scheduled", - detail: "reason=max-duration attempt=1 delayMs=1000", - }); - - await vi.advanceTimersByTimeAsync(1000); - await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2)); - const secondSocket = requireSocket(1); - openSocket(secondSocket); - emitSessionUpdated(secondSocket); - - await vi.waitFor(() => - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "session.rotation.ready", - detail: "reason=max-duration", - }), - ); - await vi.waitFor(() => - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "session.reconnect.ready", - detail: "reason=max-duration attempt=1", - }), - ); - expect(bridge.isConnected()).toBe(true); - expect(onReady).toHaveBeenCalledOnce(); - - bridge.close(); - }); - - it("clears canceled rotation metadata before an explicit reconnect", async () => { - vi.useFakeTimers(); - const onClose = vi.fn(); - const onError = vi.fn(); - const onEvent = vi.fn(); - const onReady = vi.fn(); - const bridge = createNativeBridge({ onClose, onError, onEvent, onReady }); - const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); - - firstSocket.deferClose = true; - openSocket(firstSocket); - emitSessionUpdated(firstSocket); - await connecting; - expect(onReady).toHaveBeenCalledOnce(); - - emitServerEvent(firstSocket, { - type: "error", - error: { message: "Your session hit the maximum duration of 60 minutes." }, - }); - expect(firstSocket.closed).toBe(true); - - bridge.close(); - bridge.close(); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("completed"); - - const { connecting: reconnecting, socket: secondSocket } = beginBridgeConnection(bridge, 1); - firstSocket.emitDeferredClose(); - openSocket(secondSocket); - emitSessionUpdated(secondSocket); - await reconnecting; - - expect(onReady).toHaveBeenCalledTimes(2); - expect(onEvent).not.toHaveBeenCalledWith( - expect.objectContaining({ type: "session.rotation.ready" }), - ); - expect(onError).not.toHaveBeenCalled(); - - secondSocket.readyState = FakeWebSocket.CLOSED; - secondSocket.emit("close", 1006, Buffer.from("ordinary drop")); - await vi.advanceTimersByTimeAsync(0); - - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "session.reconnect.scheduled", - detail: "reason=websocket-close attempt=1 delayMs=1000", - }); - expect(onEvent).not.toHaveBeenCalledWith( - expect.objectContaining({ - type: "session.reconnect.scheduled", - detail: expect.stringContaining("reason=max-duration"), - }), - ); - - bridge.close(); - await vi.advanceTimersByTimeAsync(0); - expect(vi.getTimerCount()).toBe(0); - expect(onClose).toHaveBeenCalledTimes(2); - expect(onClose).toHaveBeenLastCalledWith("completed"); - }); - - it("cancels a pending reconnect and allows a later explicit connect", async () => { - vi.useFakeTimers(); - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - emitSessionUpdated(socket); - await connecting; - - socket.readyState = FakeWebSocket.CLOSED; - socket.emit("close", 1006, Buffer.from("transient drop")); - await vi.advanceTimersByTimeAsync(0); - expect(vi.getTimerCount()).toBe(1); - - bridge.close(); - await vi.advanceTimersByTimeAsync(0); - - expect(vi.getTimerCount()).toBe(0); - expect(FakeWebSocket.instances).toHaveLength(1); - expect(onError).not.toHaveBeenCalled(); - - const { connecting: reconnecting, socket: reconnectedSocket } = beginBridgeConnection( - bridge, - 1, - ); - openSocket(reconnectedSocket); - emitSessionUpdated(reconnectedSocket); - await reconnecting; - - expect(bridge.isConnected()).toBe(true); - expect(FakeWebSocket.instances).toHaveLength(2); - expect(onError).not.toHaveBeenCalled(); - bridge.close(); - }); - - it("does not report reconnect readiness after cancellation during provider setup", async () => { - vi.useFakeTimers(); - const onClose = vi.fn(); - const onError = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onClose, onError, onEvent }); - const socket = await connectReadyBridge(bridge); - - socket.readyState = FakeWebSocket.CLOSED; - socket.emit("close", 1006, Buffer.from("transient drop")); - await vi.advanceTimersByTimeAsync(1000); - const retrySocket = requireSocket(1); - openSocket(retrySocket); - - bridge.close(); - await vi.advanceTimersByTimeAsync(0); - - expect(onEvent).not.toHaveBeenCalledWith( - expect.objectContaining({ type: "session.reconnect.ready" }), - ); - expect(onError).not.toHaveBeenCalled(); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("completed"); - }); - - it("lets cancellation win a queued reconnect startup error", async () => { - vi.useFakeTimers(); - const onClose = vi.fn(); - const onError = vi.fn(); - const bridge = createNativeBridge({ onClose, onError }); - const socket = await connectReadyBridge(bridge); - - socket.readyState = FakeWebSocket.CLOSED; - socket.emit("close", 1006, Buffer.from("transient drop")); - await vi.advanceTimersByTimeAsync(1000); - const retrySocket = requireSocket(1); - openSocket(retrySocket); - emitServerEvent(retrySocket, { - type: "error", - error: { message: "queued retry startup failure" }, - }); - - bridge.close(); - await vi.advanceTimersByTimeAsync(0); - - expect(onError).not.toHaveBeenCalled(); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("completed"); - expect(vi.getTimerCount()).toBe(0); - }); - - it("reports one terminal error for malformed audio during reconnect setup", async () => { - vi.useFakeTimers(); - const onClose = vi.fn(); - const onError = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onClose, onError, onEvent }); - const socket = await connectReadyBridge(bridge); - - socket.readyState = FakeWebSocket.CLOSED; - socket.emit("close", 1006, Buffer.from("transient drop")); - await vi.advanceTimersByTimeAsync(1000); - const retrySocket = requireSocket(1); - openSocket(retrySocket); - emitServerEvent(retrySocket, { - type: "response.output_audio.delta", - item_id: "item_1", - delta: "not-base64!", - }); - await vi.advanceTimersByTimeAsync(0); - - expect(onError).toHaveBeenCalledOnce(); - expect(onError).toHaveBeenCalledWith( - new Error("OpenAI realtime stream returned malformed base64 audio data"), - ); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("error"); - expect(onEvent).not.toHaveBeenCalledWith( - expect.objectContaining({ type: "session.reconnect.ready" }), - ); - expect(vi.getTimerCount()).toBe(0); - }); - - it("ignores late events from a socket replaced by reconnect", async () => { - vi.useFakeTimers(); - const onAudio = vi.fn(); - const onClose = vi.fn(); - const onError = vi.fn(); - const bridge = createNativeBridge({ - onAudio, - onClose, - onError, - }); - const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); - - openSocket(firstSocket); - emitSessionUpdated(firstSocket); - await connecting; - - firstSocket.readyState = FakeWebSocket.CLOSED; - firstSocket.emit("close", 1006, Buffer.from("transient drop")); - firstSocket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - delta: Buffer.from("late audio").toString("base64"), - }), - ), - ); - firstSocket.emit("error", new Error("late retry-wait failure")); - expect(onAudio).not.toHaveBeenCalled(); - expect(onError).not.toHaveBeenCalled(); - - await vi.advanceTimersByTimeAsync(1000); - const secondSocket = requireSocket(1); - openSocket(secondSocket); - emitSessionUpdated(secondSocket); - await vi.waitFor(() => expect(bridge.isConnected()).toBe(true)); - - emitSessionUpdated(firstSocket); - firstSocket.emit("error", new Error("late socket failure")); - firstSocket.emit("close", 1006, Buffer.from("late socket close")); - await vi.advanceTimersByTimeAsync(0); - - expect(bridge.isConnected()).toBe(true); - expect(FakeWebSocket.instances).toHaveLength(2); - expect(vi.getTimerCount()).toBe(0); - expect(onError).not.toHaveBeenCalled(); - expect(onClose).not.toHaveBeenCalled(); - bridge.close(); - }); - - it("exhausts retries when sockets open but never become provider-ready", async () => { - vi.useFakeTimers(); - const onClose = vi.fn(); - const onError = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onClose, onError, onEvent }); - const { connecting, socket: firstSocket } = beginBridgeConnection(bridge); - - openSocket(firstSocket); - emitSessionUpdated(firstSocket); - await connecting; - - firstSocket.readyState = FakeWebSocket.CLOSED; - firstSocket.emit("close", 1006, Buffer.from("transient drop")); - - for (let attempt = 1; attempt <= 5; attempt += 1) { - await vi.waitFor(() => - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "session.reconnect.scheduled", - detail: `reason=websocket-close attempt=${attempt} delayMs=${1000 * 2 ** (attempt - 1)}`, - }), - ); - await vi.advanceTimersByTimeAsync(1000 * 2 ** (attempt - 1)); - const retrySocket = requireSocket(attempt); - openSocket(retrySocket); - retrySocket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { message: `retry startup failure ${attempt}` }, - }), - ), - ); - } - - await vi.waitFor(() => expect(onClose).toHaveBeenCalledWith("error")); - expect(onClose).toHaveBeenCalledOnce(); - expect(onError).toHaveBeenCalledTimes(5); - expect(FakeWebSocket.instances).toHaveLength(6); - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "session.reconnect.exhausted", - detail: "reason=websocket-close attempts=5", - }); - - bridge.close(); - expect(onClose).toHaveBeenCalledOnce(); - }); - - it("keeps Azure deployment bridges on deployment-compatible session payloads", async () => { - const bridge = createNativeBridge({ - providerConfig: { - apiKey: "sk-test", // pragma: allowlist secret - azureEndpoint: "https://example.openai.azure.com/", - azureDeployment: "realtime-prod", - azureApiVersion: "2024-10-01-preview", - voice: "verse", - }, - audioFormat: REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, - instructions: "Be helpful.", - tools: [ - createRealtimeTool("1_lookup"), - createRealtimeTool("calendar.lookup:next"), - createRealtimeTool("x".repeat(65)), - ], - }); - const { connecting, socket } = beginBridgeConnection(bridge); - - expect(socket.args[0]).toBe( - "wss://example.openai.azure.com/openai/realtime?api-version=2024-10-01-preview&deployment=realtime-prod", - ); - - openSocket(socket); - await Promise.resolve(); - - const session = requireSession(socket); - expectRecordFields(session, "session", { - modalities: ["text", "audio"], - instructions: "Be helpful.", - voice: "verse", - input_audio_format: "pcm16", - output_audio_format: "pcm16", - input_audio_transcription: { model: "whisper-1" }, - temperature: 0.8, - }); - expectRecordFields( - requireRecord(session.turn_detection, "session turn detection"), - "turn detection", - { - create_response: true, - }, - ); - expect(session).not.toHaveProperty("type"); - expect(session).not.toHaveProperty("audio"); - const tools = session.tools as Array<{ name?: string }>; - expect(tools.map((tool) => tool.name)).toEqual(["1_lookup"]); - - emitSessionUpdated(socket); - await connecting; - - bridge.triggerGreeting?.("Say hello."); - expect(parseSent(socket).slice(-2)).toEqual([ - { - type: "session.update", - session: { - turn_detection: { - type: "server_vad", - threshold: 0.5, - prefix_padding_ms: 300, - silence_duration_ms: 500, - create_response: false, - }, - }, - }, - expectedResponseCreateEvent(), - ]); - - emitServerEvent(socket, { type: "response.done" }); - expect(parseSent(socket).at(-1)).toEqual({ - type: "session.update", - session: { - turn_detection: { - type: "server_vad", - threshold: 0.5, - prefix_padding_ms: 300, - silence_duration_ms: 500, - create_response: true, - }, - }, - }); - }); - - it("rejects connection when session configuration fails before readiness", async () => { - const bridge = createNativeBridge(); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { message: "invalid realtime session" }, - }), - ), - ); - - await expect(connecting).rejects.toThrow("invalid realtime session"); - expect(bridge.isConnected()).toBe(false); - }); - - it("treats pre-ready auth errors as a single startup failure", async () => { - const onError = vi.fn(); - const onClose = vi.fn(); - const bridge = createNativeBridge({ onError, onClose }); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { message: "Incorrect API key provided: sk-proj-***" }, - }), - ), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { message: "Incorrect API key provided: sk-proj-***" }, - }), - ), - ); - - await expect(connecting).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); - expect(onError).not.toHaveBeenCalled(); - expect(onClose).not.toHaveBeenCalled(); - expect(socket.closed).toBe(true); - expect(bridge.isConnected()).toBe(false); - }); - - it("normalizes structured direct OpenAI startup auth errors", async () => { - const bridge = createNativeBridge(); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { - type: "invalid_request_error", - code: "invalid_api_key", - message: "Invalid API key", - }, - }), - ), - ); - - await expect(connecting).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); - expect(bridge.isConnected()).toBe(false); - }); - - it("normalizes direct OpenAI socket handshake auth errors", async () => { - const bridge = createNativeBridge(); - const { connecting, socket } = beginBridgeConnection(bridge); - - socket.emit("error", new Error("Unexpected server response: 401")); - - await expect(connecting).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); - expect(bridge.isConnected()).toBe(false); - }); - - it.each([ - [ - "Azure deployment", - { - apiKey: "sk-test", // pragma: allowlist secret - azureEndpoint: "https://example.openai.azure.com", - azureDeployment: "realtime-prod", - }, - ], - [ - "custom endpoint", - { - apiKey: "sk-test", // pragma: allowlist secret - azureEndpoint: "https://realtime-proxy.example.com", - }, - ], - ])("preserves %s startup auth errors", async (_label, providerConfig) => { - const bridge = createNativeBridge({ - providerConfig, - }); - const { connecting, socket } = beginBridgeConnection(bridge); - - socket.emit("error", new Error("Unexpected server response: 401")); - - await expect(connecting).rejects.toThrow("Unexpected server response: 401"); - expect(bridge.isConnected()).toBe(false); - }); - - it("keeps a retried connection ready after delayed startup failure close", async () => { - const onClose = vi.fn(); - const bridge = createNativeBridge({ onClose }); - const { connecting: failedConnect, socket: failedSocket } = beginBridgeConnection(bridge); - failedSocket.deferClose = true; - - openSocket(failedSocket); - failedSocket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { message: "Incorrect API key provided" }, - }), - ), - ); - - await expect(failedConnect).rejects.toThrow(OPENAI_REALTIME_REJECTED_KEY_MESSAGE); - expect(failedSocket.deferredClose).toBeDefined(); - - const { connecting: retryConnect, socket: retrySocket } = beginBridgeConnection(bridge, 1); - openSocket(retrySocket); - emitSessionUpdated(retrySocket); - await retryConnect; - - expect(bridge.isConnected()).toBe(true); - failedSocket.emitDeferredClose(); - expect(bridge.isConnected()).toBe(true); - expect(onClose).not.toHaveBeenCalled(); - }); - - it("rejects connection when the socket closes before session readiness", async () => { - const bridge = createNativeBridge(); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - socket.close(1006, "session closed"); - - await expect(connecting).rejects.toThrow("OpenAI realtime connection closed before ready"); - expect(bridge.isConnected()).toBe(false); - }); - - it("bounds sideband frames received before session readiness", async () => { - const bridge = createNativeBridge(); - const { connecting, socket } = beginBridgeConnection(bridge); - openSocket(socket); - const frame = Buffer.from( - JSON.stringify({ type: "session.created", padding: "x".repeat(600 * 1024) }), - ); - - socket.emit("message", frame); - socket.emit("message", frame); - - await expect(connecting).rejects.toThrow("sideband startup buffer exceeded"); - expect(bridge.isConnected()).toBe(false); - }); - - it("does not report startup timeout shutdown as a clean close", async () => { - vi.useFakeTimers(); - const onClose = vi.fn(); - const bridge = createNativeBridge({ onClose }); - const { connecting, socket } = beginBridgeConnection(bridge); - - const timeoutAssertion = expect(connecting).rejects.toThrow( - "OpenAI realtime connection timeout", - ); - await vi.advanceTimersByTimeAsync(10_000); - await timeoutAssertion; - expect(socket.terminated).toBe(true); - expect(onClose).not.toHaveBeenCalled(); - expect(FakeWebSocket.instances).toHaveLength(1); - expect(bridge.isConnected()).toBe(false); - }); - - it("can disable automatic audio turn responses for agent-routed voice loops", async () => { - const bridge = createNativeBridge({ - autoRespondToAudio: false, - }); - const { connecting, socket } = beginBridgeConnection(bridge); - - openSocket(socket); - emitSessionUpdated(socket); - await connecting; - - expectRecordFields( - requireNestedRecord(requireSession(socket), ["audio", "input", "turn_detection"]), - "turn detection", - { - create_response: false, - interrupt_response: false, - }, - ); - }); - - it("can disable realtime response interruption while keeping audio responses enabled", async () => { - const bridge = createNativeBridge({ - autoRespondToAudio: true, - interruptResponseOnInputAudio: false, - }); - const socket = await connectReadyBridge(bridge); - - expectRecordFields( - requireNestedRecord(requireSession(socket), ["audio", "input", "turn_detection"]), - "turn detection", - { - create_response: true, - interrupt_response: false, - }, - ); - }); - - it("does not locally clear playback on speech-start events when input interruption is disabled", async () => { - const onAudio = vi.fn(); - const onClearAudio = vi.fn(); - const bridge = createNativeBridge({ - autoRespondToAudio: true, - interruptResponseOnInputAudio: false, - onAudio, - onClearAudio, - }); - const socket = await connectReadyBridge(bridge); - - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "input_audio_buffer.speech_started" })), - ); - - expect(onAudio).toHaveBeenCalledTimes(1); - expect(onClearAudio).not.toHaveBeenCalled(); - expect(hasSentEventType(socket, "response.cancel")).toBe(false); - expect(hasSentEventType(socket, "conversation.item.truncate")).toBe(false); - }); - - it("keeps assistant playback active on server VAD when automatic audio responses are disabled", async () => { - const onAudio = vi.fn(); - const onClearAudio = vi.fn(); - const bridge = createNativeBridge({ - autoRespondToAudio: false, - onAudio, - onClearAudio, - }); - const socket = await connectReadyBridge(bridge); - - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "input_audio_buffer.speech_started" })), - ); - - expect(onAudio).toHaveBeenCalledTimes(1); - expect(onClearAudio).not.toHaveBeenCalled(); - expect(hasSentEventType(socket, "response.cancel")).toBe(false); - expect(hasSentEventType(socket, "conversation.item.truncate")).toBe(false); - }); - - it("can request PCM16 24 kHz realtime audio for Chrome command-pair bridges", async () => { - const bridge = createNativeBridge({ - audioFormat: REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, - }); - const socket = await connectReadyBridge(bridge); - - const session = requireSession(socket); - expect(requireNestedRecord(session, ["audio", "input", "format"])).toEqual({ - type: "audio/pcm", - rate: 24000, - }); - expect(requireNestedRecord(session, ["audio", "output", "format"])).toEqual({ - type: "audio/pcm", - rate: 24000, - }); - }); - - it("settles cleanly when closed before the websocket opens", async () => { - const onClose = vi.fn(); - const bridge = createNativeBridge({ onClose }); - const { connecting, socket } = beginBridgeConnection(bridge); - - bridge.close(); - bridge.close(); - - await expect(connecting).resolves.toBeUndefined(); - expect(socket.closed).toBe(true); - expect(socket.terminated).toBe(false); - expect(onClose).toHaveBeenCalledOnce(); - expect(onClose).toHaveBeenCalledWith("completed"); - }); - - it("truncates externally interrupted playback after an immediate mark acknowledgement", async () => { - const onAudio = vi.fn(); - const onClearAudio = vi.fn(); - const bridge = createNativeBridge({ - onAudio, - onClearAudio, - onMark: () => bridge.acknowledgeMark(), - }); - const socket = await connectReadyBridge(bridge); - - bridge.setMediaTimestamp(1000); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - bridge.setMediaTimestamp(1300); - - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - - expect(onAudio).toHaveBeenCalledTimes(1); - expect(onClearAudio).toHaveBeenCalledWith("barge-in"); - expect(parseSent(socket).slice(-2)).toEqual([ - expectedResponseCancelEvent(), - { - type: "conversation.item.truncate", - item_id: "item_1", - content_index: 0, - audio_end_ms: 300, - }, - ]); - }); - - it("preserves FIFO playback acknowledgements after sustained output", async () => { - const onClearAudio = vi.fn(); - const onMark = vi.fn(); - const bridge = createNativeBridge({ - onClearAudio, - onMark, - }); - const socket = await connectReadyBridge(bridge); - - bridge.setMediaTimestamp(1000); - for (let index = 0; index < 300; index += 1) { - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - } - - const marks = onMark.mock.calls.map(([markName]) => String(markName)); - expect(marks).toHaveLength(300); - for (let index = 0; index < 299; index += 1) { - bridge.acknowledgeMark(); - } - bridge.setMediaTimestamp(1300); - bridge.handleBargeIn?.(); - - expect(parseSent(socket).slice(-1)).toEqual([ - { - type: "conversation.item.truncate", - item_id: "item_1", - content_index: 0, - audio_end_ms: 300, - }, - ]); - expect(onClearAudio).toHaveBeenCalledWith("barge-in"); - - for (let index = 0; index < 300; index += 1) { - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - } - const latestMark = onMark.mock.calls.at(-1)?.[0]; - if (typeof latestMark !== "string") { - throw new Error("expected a playback mark"); - } - bridge.acknowledgeMark(latestMark); - bridge.setMediaTimestamp(1600); - bridge.handleBargeIn?.(); - - expect( - parseSent(socket).filter((event) => event.type === "conversation.item.truncate"), - ).toHaveLength(1); - bridge.close(); - }); - - it("treats a later named mark as cumulative playback progress", async () => { - const onMark = vi.fn(); - const bridge = createNativeBridge({ onMark }); - const socket = await connectReadyBridge(bridge); - - bridge.setMediaTimestamp(1000); - for (let index = 0; index < 3; index += 1) { - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - } - const marks = onMark.mock.calls.map(([markName]) => String(markName)); - expect(marks).toHaveLength(3); - - bridge.acknowledgeMark(marks[2]); - bridge.acknowledgeMark(marks[0]); - bridge.acknowledgeMark(marks[1]); - bridge.setMediaTimestamp(1300); - bridge.handleBargeIn?.(); - - expect( - parseSent(socket).filter((event) => event.type === "conversation.item.truncate"), - ).toHaveLength(0); - bridge.close(); - }); - - it("forwards current realtime output audio events", async () => { - const onAudio = vi.fn(); - const onTranscript = vi.fn(); - const bridge = createNativeBridge({ - onAudio, - onTranscript, - }); - const socket = await connectReadyBridge(bridge); - - const audio = Buffer.from("assistant audio"); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.output_audio.delta", - item_id: "item_1", - delta: audio.toString("base64"), - }), - ), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.output_audio_transcript.done", - transcript: "hello from current realtime events", - }), - ), - ); - - expect(onAudio).toHaveBeenCalledWith(audio); - expect(onTranscript).toHaveBeenCalledWith( - "assistant", - "hello from current realtime events", - true, - ); - }); - - it("surfaces input transcription failures with their provider error details", async () => { - const onError = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onError, onEvent }); - const socket = await connectReadyBridge(bridge); - - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "conversation.item.input_audio_transcription.failed", - item_id: "item_speech", - error: { code: "decoder_failure", message: "speech decoder exploded" }, - }), - ), - ); - - expect(onError).toHaveBeenCalledWith( - expect.objectContaining({ message: "speech decoder exploded" }), - ); - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "conversation.item.input_audio_transcription.failed", - itemId: "item_speech", - detail: "speech decoder exploded", - }); - }); - - it("preserves corrected final text from legacy realtime text events", async () => { - const onTranscript = vi.fn(); - const bridge = createNativeBridge({ onTranscript }); - const socket = await connectReadyBridge(bridge); - - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.text.delta", delta: "draft assistant" })), - ); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.text.done", text: "corrected assistant" })), - ); - - expect(onTranscript.mock.calls).toEqual([ - ["assistant", "draft assistant", false], - ["assistant", "corrected assistant", true], - ]); - }); - - it.each([ - ["invalid alphabet", "not-base64!"], - ["non-canonical pad bits", "ZE=="], - ])("terminates the session for %s in output audio", async (_scenario, delta) => { - const onAudio = vi.fn(); - const onError = vi.fn(); - const onClose = vi.fn(); - const bridge = createNativeBridge({ - onAudio, - onError, - onClose, - }); - const socket = await connectReadyBridge(bridge); - - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.output_audio.delta", - item_id: "item_1", - delta, - }), - ), - ); - - expect(onAudio).not.toHaveBeenCalled(); - expect(onError).toHaveBeenCalledWith( - expect.objectContaining({ - message: "OpenAI realtime stream returned malformed base64 audio data", - }), - ); - expect(onClose).toHaveBeenCalledWith("error"); - expect(socket.closed).toBe(true); - await expect(bridge.connect()).rejects.toThrow( - "OpenAI realtime stream returned malformed base64 audio data", - ); - }); - - it("forwards Codex-compatible legacy realtime audio and transcript events", async () => { - const onAudio = vi.fn(); - const onTranscript = vi.fn(); - const bridge = createNativeBridge({ - onAudio, - onTranscript, - }); - const socket = await connectReadyBridge(bridge); - - const audio = Buffer.from("legacy assistant audio"); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "conversation.output_audio.delta", - data: audio.toString("base64"), - sample_rate: 24000, - channels: 1, - }), - ), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "conversation.input_transcript.delta", - delta: "partial user", - }), - ), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "conversation.output_transcript.delta", - delta: "partial assistant", - }), - ), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.output_text.done", - text: "final assistant text", - }), - ), - ); - - expect(onAudio).toHaveBeenCalledWith(audio); - expect(onTranscript).toHaveBeenCalledWith("user", "partial user", false); - expect(onTranscript).toHaveBeenCalledWith("assistant", "partial assistant", false); - expect(onTranscript).toHaveBeenCalledWith("assistant", "final assistant text", true); - }); - - it("executes tool calls only from successful response output", async () => { - const onToolCall = vi.fn(); - const bridge = createNativeBridge({ onToolCall }); - const socket = await connectReadyBridge(bridge); - - emitServerEvent(socket, { - type: "response.function_call_arguments.delta", - item_id: "item_tool_1", - name: "openclaw_agent_consult", - call_id: "call_1", - delta: '{"question":"provisional', - }); - emitServerEvent(socket, { - type: "response.function_call_arguments.done", - item_id: "item_tool_1", - name: "openclaw_agent_consult", - call_id: "call_1", - arguments: '{"question":"still provisional"}', - }); - emitServerEvent(socket, { - type: "conversation.item.done", - item: { - id: "item_tool_1", - type: "function_call", - name: "openclaw_agent_consult", - call_id: "call_1", - arguments: '{"question":"not terminal"}', - }, - }); - expect(onToolCall).not.toHaveBeenCalled(); - - const completed = { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: [ - { - id: "item_tool_1", - type: "function_call", - status: "completed", - name: "openclaw_agent_consult", - call_id: "call_1", - arguments: '{"question":"delegate this"}', - }, - ], - }, - }; - emitServerEvent(socket, completed); - emitServerEvent(socket, completed); - - expect(onToolCall).toHaveBeenCalledTimes(1); - expect(onToolCall).toHaveBeenCalledWith({ - itemId: "item_tool_1", - callId: "call_1", - name: "openclaw_agent_consult", - args: { question: "delegate this" }, - }); - }); - - it.each(["cancelled", "failed", "incomplete"])( - "ignores function calls from a %s response", - async (status) => { - const onToolCall = vi.fn(); - const bridge = createNativeBridge({ onToolCall }); - const socket = await connectReadyBridge(bridge); - - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_1", - status, - output: [ - { - id: "item_tool_1", - type: "function_call", - status: "completed", - name: "openclaw_agent_consult", - call_id: "call_1", - arguments: '{"question":"must stay inert"}', - }, - ], - }, - }); - - expect(onToolCall).not.toHaveBeenCalled(); - }, - ); - - it("ignores malformed and unfinished response output items", async () => { - const onToolCall = vi.fn(); - const bridge = createNativeBridge({ onToolCall }); - const socket = await connectReadyBridge(bridge); - - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: [ - null, - "invalid", - { - id: "item_tool_1", - type: "function_call", - status: "incomplete", - name: "openclaw_agent_consult", - call_id: "call_1", - arguments: '{"question":"unfinished"}', - }, - ], - }, - }); - - expect(onToolCall).not.toHaveBeenCalled(); - }); - - it.each([ - { - name: "an argument object", - finalArguments: '{"city":"Paris"}', - expectedArguments: { city: "Paris" }, - }, - { - name: "the shipped empty argument contract", - finalArguments: "", - expectedArguments: {}, - }, - ])( - "uses terminal response arguments for $name", - async ({ finalArguments, expectedArguments }) => { - const onToolCall = vi.fn(); - const bridge = createNativeBridge({ onToolCall }); - const socket = await connectReadyBridge(bridge); - - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: [ - { - id: "item_tool_1", - type: "function_call", - status: "completed", - call_id: "call_1", - name: "lookup_weather", - arguments: finalArguments, - }, - ], - }, - }); - - expect(onToolCall).toHaveBeenCalledWith({ - itemId: "item_tool_1", - callId: "call_1", - name: "lookup_weather", - args: expectedArguments, - }); - }, - ); - - it.each([ - { name: "malformed JSON", arguments: '{"city":', reason: "malformed-json" }, - { name: "an array", arguments: '["Paris"]', reason: "non-object-json" }, - { name: "JSON null", arguments: "null", reason: "non-object-json" }, - { name: "a number", arguments: "42", reason: "non-object-json" }, - { name: "a boolean", arguments: "true", reason: "non-object-json" }, - { name: "missing arguments", arguments: undefined, reason: "invalid-json-type" }, - { name: "non-string arguments", arguments: { city: "Paris" }, reason: "invalid-json-type" }, - ])("rejects $name per call without ending the session", async ({ arguments: args, reason }) => { - const onToolCall = vi.fn(); - const onError = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onToolCall, onError, onEvent }); - const socket = await connectReadyBridge(bridge); - const completed = { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: [ - { - id: "item_tool_1", - type: "function_call", - status: "completed", - call_id: "call_1", - name: "lookup_weather", - arguments: args, - }, - ], - }, - }; - - emitServerEvent(socket, { type: "response.created", response: { id: "response_1" } }); - emitServerEvent(socket, completed); - emitServerEvent(socket, completed); - - expect(onToolCall).not.toHaveBeenCalled(); - expect(onError).not.toHaveBeenCalled(); - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "tool_call.arguments.rejected", - detail: `reason=${reason}`, - itemId: "item_tool_1", - }); - expect( - parseSent(socket).filter( - (event) => - event.type === "conversation.item.create" && - (event.item as { call_id?: string } | undefined)?.call_id === "call_1", - ), - ).toHaveLength(1); - }); - - it.each([ - { - name: "accepts", - encoding: "ASCII", - argumentBytes: 256_000, - unit: "a", - repeat: 255_992, - suffix: "", - rejected: false, - }, - { - name: "rejects", - encoding: "ASCII", - argumentBytes: 256_001, - unit: "a", - repeat: 255_993, - suffix: "", - rejected: true, - }, - { - name: "accepts", - encoding: "multibyte", - argumentBytes: 256_000, - unit: "é", - repeat: 127_996, - suffix: "", - rejected: false, - }, - { - name: "rejects", - encoding: "multibyte", - argumentBytes: 256_001, - unit: "é", - repeat: 127_996, - suffix: "a", - rejected: true, - }, - ])( - "$name $argumentBytes-byte $encoding UTF-8 arguments", - async ({ argumentBytes, unit, repeat, suffix, rejected }) => { - const onToolCall = vi.fn(); - const onError = vi.fn(); - const bridge = createNativeBridge({ onToolCall, onError }); - const socket = await connectReadyBridge(bridge); - const rawArgs = `{"x":"${unit.repeat(repeat)}${suffix}"}`; - expect(Buffer.byteLength(rawArgs, "utf8")).toBe(argumentBytes); - - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: [ - { - id: "item_tool_1", - type: "function_call", - status: "completed", - call_id: "call_1", - name: "lookup_weather", - arguments: rawArgs, - }, - ], - }, - }); - - expect(onToolCall).toHaveBeenCalledTimes(rejected ? 0 : 1); - expect( - parseSent(socket).some( - (event) => - event.type === "conversation.item.create" && - (event.item as { call_id?: string } | undefined)?.call_id === "call_1", - ), - ).toBe(rejected); - expect(onError).not.toHaveBeenCalled(); - }, - ); - - it("ends an extreme session before terminal tool-call ids become unbounded", async () => { - const onToolCall = vi.fn(); - const onError = vi.fn(); - const onClose = vi.fn(); - const bridge = createNativeBridge({ onToolCall, onError, onClose }); - const socket = await connectReadyBridge(bridge); - - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: Array.from({ length: 1_025 }, (_, index) => ({ - id: `item_${index}`, - type: "function_call", - status: "completed", - call_id: `call_${index}`, - name: "lookup_weather", - arguments: "{}", - })), - }, - }); - - expect(onToolCall).toHaveBeenCalledTimes(1_024); - expect(onError).toHaveBeenCalledOnce(); - expect(onError).toHaveBeenCalledWith( - new Error("OpenAI realtime tool-call session limit exceeded (1024)"), - ); - expect(onClose).toHaveBeenCalledWith("error"); - expect(socket.closed).toBe(true); - await expect(bridge.connect()).rejects.toThrow( - "OpenAI realtime tool-call session limit exceeded (1024)", - ); - }); - - it("stops dispatching terminal output when a tool callback closes the bridge", async () => { - const onToolCall = vi.fn(); - const bridge = createNativeBridge({ onToolCall }); - onToolCall.mockImplementation(() => bridge.close()); - const socket = await connectReadyBridge(bridge); - - emitServerEvent(socket, { - type: "response.done", - response: { - id: "response_1", - status: "completed", - output: Array.from({ length: 2 }, (_, index) => ({ - id: `item_${index}`, - type: "function_call", - status: "completed", - call_id: `call_${index}`, - name: "lookup_weather", - arguments: "{}", - })), - }, - }); - - expect(onToolCall).toHaveBeenCalledTimes(1); - }); - - it("creates an explicit user item and response for manual speech", async () => { - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onEvent }); - const socket = await connectReadyBridge(bridge); - - bridge.triggerGreeting?.("Say exactly: hello from explicit speech."); - - const sent = parseSent(socket); - expect(sent[1]).toEqual({ - type: "conversation.item.create", - item: { - type: "message", - role: "user", - content: [ - { - type: "input_text", - text: "Say exactly: hello from explicit speech.", - }, - ], - }, - }); - expectRecordFields( - requireNestedRecord(sent[2]?.session, ["audio", "input", "turn_detection"]), - "manual response turn detection", - { - create_response: false, - interrupt_response: true, - }, - ); - expect(sent[3]).toEqual(expectedResponseCreateEvent()); - expect(JSON.stringify(parseSent(socket).at(-1))).not.toContain("output_modalities"); - expect(onEvent).toHaveBeenCalledWith({ direction: "client", type: "conversation.item.create" }); - expect(onEvent).toHaveBeenCalledWith({ direction: "client", type: "response.create" }); - - emitServerEvent(socket, { type: "response.done" }); - - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); - - it("forces one host-selected function on an otherwise automatic response", async () => { - const bridge = createNativeBridge(); - const socket = await connectReadyBridge(bridge); - - bridge.sendUserMessage?.("Run the deterministic check.", { - toolChoice: { type: "function", name: "lookup_weather" }, - }); - - expect(parseSent(socket).at(-1)).toEqual({ - type: "response.create", - event_id: expect.stringMatching(/^openclaw-response-create-/), - response: { - output_modalities: ["audio"], - tool_choice: { type: "function", name: "lookup_weather" }, - }, - }); - }); - - it("defers manual response.create while a realtime response is active", async () => { - const bridge = createNativeBridge(); - const socket = await connectReadyBridge(bridge); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - - bridge.sendUserMessage?.("queued manual response"); - - expect(parseSent(socket).slice(-1)).toEqual([ - { - type: "conversation.item.create", - item: { - type: "message", - role: "user", - content: [{ type: "input_text", text: "queued manual response" }], - }, - }, - ]); - - emitServerEvent(socket, { type: "response.done" }); - - expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); - }); - - it("restores automatic audio responses when a manual response is rejected", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const socket = await connectReadyBridge(bridge); - - bridge.triggerGreeting?.("Say exactly: hello from explicit speech."); - - const responseCreateEvent = parseSent(socket).findLast( - (event) => event.type === "response.create", - ); - if (!responseCreateEvent?.event_id) { - throw new Error("expected response.create event id"); - } - - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-2)?.session, ["audio", "input", "turn_detection"]), - "suppressed turn detection", - { - create_response: false, - interrupt_response: true, - }, - ); - - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { - event_id: responseCreateEvent.event_id, - message: "bad response request", - }, - }), - ), - ); - - expect(onError).toHaveBeenCalledWith(new Error("bad response request")); - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); - - it("keeps automatic audio suppressed for unrelated errors during a manual response", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const socket = await connectReadyBridge(bridge); - - bridge.triggerGreeting?.("Say exactly: hello from explicit speech."); - const sessionUpdatesBeforeError = parseSent(socket).filter( - (event) => event.type === "session.update", - ); - - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { event_id: "unrelated-audio-event", message: "bad audio append" }, - }), - ), - ); - - expect(onError).toHaveBeenCalledWith(new Error("bad audio append")); - expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength( - sessionUpdatesBeforeError.length, - ); - - emitServerEvent(socket, { type: "response.done" }); - - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); - - it("flushes a queued manual response after the prior request is rejected", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const socket = await connectReadyBridge(bridge); - - bridge.triggerGreeting?.("Say exactly: first greeting."); - const firstResponseCreate = parseSent(socket).findLast( - (event) => event.type === "response.create", - ); - if (!firstResponseCreate?.event_id) { - throw new Error("expected first response.create event id"); - } - const sessionUpdateCount = parseSent(socket).filter( - (event) => event.type === "session.update", - ).length; - - bridge.sendUserMessage?.("Say exactly: queued follow-up."); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { - event_id: firstResponseCreate.event_id, - message: "bad response request", - }, - }), - ), - ); - - const responseCreates = parseSent(socket).filter((event) => event.type === "response.create"); - expect(responseCreates).toHaveLength(2); - expect(responseCreates[1]).toEqual(expectedResponseCreateEvent()); - expect(responseCreates[1]?.event_id).not.toBe(firstResponseCreate.event_id); - expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength( - sessionUpdateCount, - ); - expect(onError).toHaveBeenCalledWith(new Error("bad response request")); - - emitServerEvent(socket, { type: "response.done" }); - - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); - - it.each([ - ["undefined", (): undefined => undefined], - ["function", () => () => undefined], - ["symbol", () => Symbol("invalid-tool-result")], - ["bigint", () => ({ value: 1n })], - [ - "circular", - () => { - const result: { self?: unknown } = {}; - result.self = result; - return result; - }, - ], - ["omitted custom serialization", () => ({ toJSON: () => undefined })], - ] as const)( - "rejects %s tool results without consuming a retryable call", - async (_label, create) => { - const bridge = createNativeBridge({ onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket); - const previousEventCount = socket.sent.length; - - expect(() => bridge.submitToolResult("call_1", create())).toThrow(); - expect(socket.sent).toHaveLength(previousEventCount); - expect(hasSentEventType(socket, "response.create")).toBe(false); - - await bridge.submitToolResult("call_1", { recovered: true }); - - expect(parseSent(socket).find((event) => event.type === "conversation.item.create")).toEqual({ - type: "conversation.item.create", - item: { - type: "function_call_output", - call_id: "call_1", - output: JSON.stringify({ recovered: true }), - }, - }); - }, - ); - - it("preserves valid JSON tool results and invokes custom serialization once", async () => { - const bridge = createNativeBridge({ onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - const values: unknown[] = [null, false, 0, "", "text", [1], { ok: true }]; - const customSerialization = vi.fn((key: string) => ({ key })); - values.push({ toJSON: customSerialization }); - const callIds = values.map((_, index) => `call_${index}`); - emitCompletedToolCalls(socket, callIds); - - for (const [index, result] of values.entries()) { - await bridge.submitToolResult(callIds[index]!, result, { suppressResponse: true }); - } - - const outputs = parseSent(socket) - .filter((event) => event.type === "conversation.item.create") - .map((event) => (event.item as { output: string }).output); - expect(outputs).toEqual([ - "null", - "false", - "0", - '""', - '"text"', - "[1]", - '{"ok":true}', - '{"key":""}', - ]); - expect(customSerialization).toHaveBeenCalledExactlyOnceWith(""); - }); - - it("does not request a realtime response for continuing tool results", async () => { - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onEvent, onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket); - - const working = bridge.submitToolResult( - "call_1", - { status: "working" }, - { willContinue: true }, - ); - - expect(parseSent(socket).slice(-1)).toEqual([ - expectedFunctionOutput("call_1", { status: "working" }), - ]); - expect(hasSentEventType(socket, "response.create")).toBe(false); - expect(working).toBeUndefined(); - - const done = bridge.submitToolResult("call_1", { text: "done" }); - expect(done).toBeUndefined(); - - expect(parseSent(socket).slice(-3)).toEqual([ - expectedFunctionOutput("call_1", { text: "done" }), - expect.objectContaining({ type: "session.update" }), - expectedResponseCreateEvent(), - ]); - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); - emitFunctionOutputAdded(socket, "call_1"); - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "conversation.item.added", - detail: "itemType=function_call_output", - }); - emitServerEvent(socket, { - type: "conversation.item.done", - item: { type: "function_call_output", call_id: "call_1" }, - }); - expect(onEvent).toHaveBeenCalledWith({ - direction: "server", - type: "conversation.item.done", - detail: "itemType=function_call_output", - }); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_2" } })), - ); - emitServerEvent(socket, { type: "response.done" }); - - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); - }); - - it("does not request a realtime response for suppressed tool results", async () => { - const bridge = createNativeBridge({ onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket); - - const submission = bridge.submitToolResult( - "call_1", - { status: "already_delivered" }, - { suppressResponse: true }, - ); - - expect(parseSent(socket).slice(-1)).toEqual([ - expectedFunctionOutput("call_1", { status: "already_delivered" }), - ]); - emitFunctionOutputAdded(socket, "call_1"); - await submission; - expect(hasSentEventType(socket, "response.create")).toBe(false); - }); - - it("waits for every parallel tool result before continuing the response", async () => { - const bridge = createNativeBridge({ onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket, ["call_1", "call_2"]); - - const first = bridge.submitToolResult("call_1", { text: "first" }); - emitFunctionOutputAdded(socket, "call_1"); - await first; - - expect(parseSent(socket).filter((event) => event.type === "response.create")).toEqual([]); - - const second = bridge.submitToolResult("call_2", { text: "second" }); - emitFunctionOutputAdded(socket, "call_2"); - await second; - - expect( - parseSent(socket).filter((event) => event.type === "conversation.item.create"), - ).toHaveLength(2); - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); - }); - - it("releases a deferred continuation when the last parallel result is suppressed", async () => { - const bridge = createNativeBridge({ onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket, ["call_1", "call_2"]); - - const first = bridge.submitToolResult("call_1", { text: "first" }); - const second = bridge.submitToolResult( - "call_2", - { status: "already_delivered" }, - { suppressResponse: true }, - ); - emitFunctionOutputAdded(socket, "call_1"); - emitFunctionOutputAdded(socket, "call_2"); - await Promise.all([first, second]); - - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); - }); - - it("resets consumer tool ownership before a fresh reconnect can reuse a call id", async () => { - vi.useFakeTimers(); - const staleWork = new AbortController(); - const onEvent = vi.fn((event: RealtimeVoiceBridgeEvent) => { - if (event.direction === "client" && event.type === "session.continuity.reset") { - staleWork.abort(); - } - }); - const onToolCall = vi.fn(); - const bridge = createNativeBridge({ onEvent, onToolCall }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket, ["call_reused"]); - expect(onToolCall).toHaveBeenCalledTimes(1); - - socket.emit("close", 1006, Buffer.from("transient drop")); - const lifecycleEvents = onEvent.mock.calls.map(([event]) => event.type); - expect(lifecycleEvents.indexOf("session.continuity.reset")).toBeLessThan( - lifecycleEvents.indexOf("session.reconnect.scheduled"), - ); - await vi.advanceTimersByTimeAsync(1000); - const reconnectedSocket = requireSocket(1); - openSocket(reconnectedSocket); - emitSessionUpdated(reconnectedSocket); - - emitCompletedToolCalls(socket, ["call_from_old_socket"]); - expect( - parseSent(reconnectedSocket).filter((event) => event.type === "conversation.item.create"), - ).toEqual([]); - expect(onToolCall).toHaveBeenCalledTimes(1); - - emitCompletedToolCalls(reconnectedSocket, ["call_reused"]); - if (!staleWork.signal.aborted) { - void bridge.submitToolResult("call_reused", { text: "stale" }); - } - const fresh = bridge.submitToolResult("call_reused", { text: "fresh" }); - emitFunctionOutputAdded(reconnectedSocket, "call_reused"); - await fresh; - - expect(onToolCall).toHaveBeenCalledTimes(2); - expect( - parseSent(reconnectedSocket) - .filter( - (event) => - event.type === "conversation.item.create" && - (event.item as { call_id?: string } | undefined)?.call_id === "call_reused", - ) - .map((event) => (event.item as { output?: string } | undefined)?.output), - ).toEqual([JSON.stringify({ text: "fresh" })]); - }); - - it("does not flush deferred response.create while a tool result is still continuing", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError, onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - - emitCompletedToolCalls(socket); - const working = bridge.submitToolResult( - "call_1", - { status: "working" }, - { willContinue: true }, - ); - emitFunctionOutputAdded(socket, "call_1"); - await working; - bridge.sendUserMessage?.("queue after tool result"); - - expect(onError).not.toHaveBeenCalled(); - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_status" } })), - ); - emitServerEvent(socket, { - type: "response.done", - response: { id: "resp_status", status: "completed", output: [] }, - }); - - const done = bridge.submitToolResult("call_1", { text: "done" }); - emitFunctionOutputAdded(socket, "call_1"); - await done; - - expect(parseSent(socket).slice(-3)).toEqual([ - expectedFunctionOutput("call_1", { text: "done" }), - expect.objectContaining({ type: "session.update" }), - expectedResponseCreateEvent(), - ]); - }); - - it("serializes standalone control speech while an agent tool call is pending", async () => { - const bridge = createNativeBridge({ onToolCall: vi.fn() }); - const socket = await connectReadyBridge(bridge); - emitCompletedToolCalls(socket); - - for (const text of ["status", "steer", "cancel"]) { - bridge.sendUserMessage?.(text); - } - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); - - for (let index = 0; index < 3; index += 1) { - socket.emit( - "message", - Buffer.from( - JSON.stringify({ type: "response.created", response: { id: `resp_control_${index}` } }), - ), - ); - emitServerEvent(socket, { - type: "response.done", - response: { id: `resp_control_${index}`, status: "completed", output: [] }, - }); - expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength( - Math.min(index + 2, 3), - ); - } - }); - - it("drains deferred response.create after response.cancelled", async () => { - const bridge = createNativeBridge(); - const socket = await connectReadyBridge(bridge); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - - bridge.sendUserMessage?.("queued after cancellation"); - socket.emit("message", Buffer.from(JSON.stringify({ type: "response.cancelled" }))); - - expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); - }); - - it("does not send duplicate response.cancel while cancellation is pending", async () => { - const onEvent = vi.fn(); - const bridge = createNativeBridge({ onEvent }); - const socket = await connectReadyBridge(bridge); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - bridge.setMediaTimestamp(1000); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - bridge.setMediaTimestamp(1300); - - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - - expect(parseSent(socket).filter((event) => event.type === "response.cancel")).toHaveLength(1); - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "response.cancel", - detail: "reason=barge-in", - }); - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "conversation.item.truncate", - detail: "reason=barge-in audioEndMs=300", - }); - }); - - it("ignores zero-length playback barge-in without clearing audio", async () => { - const onClearAudio = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ - onClearAudio, - onEvent, - }); - const socket = await connectReadyBridge(bridge); - bridge.setMediaTimestamp(1000); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - - expect(onClearAudio).not.toHaveBeenCalled(); - expect(hasSentEventType(socket, "response.cancel")).toBe(false); - expect(parseSent(socket).some((event) => event.type === "conversation.item.truncate")).toBe( - false, - ); - expect(onEvent).toHaveBeenCalledWith({ - direction: "client", - type: "conversation.item.truncate.skipped", - detail: "reason=barge-in audioEndMs=0 minAudioEndMs=250", - }); - }); - - it("force-cancels zero-length playback barge-in for agent handoff fallback", async () => { - const onClearAudio = vi.fn(); - const onEvent = vi.fn(); - const bridge = createNativeBridge({ - onClearAudio, - onEvent, - }); - const socket = await connectReadyBridge(bridge); - bridge.setMediaTimestamp(1000); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - - bridge.handleBargeIn?.({ audioPlaybackActive: true, force: true }); - - expect(parseSent(socket).slice(-2)).toEqual([ - expectedResponseCancelEvent(), - { - type: "conversation.item.truncate", - item_id: "item_1", - content_index: 0, - audio_end_ms: 0, - }, - ]); - expect(onClearAudio).toHaveBeenCalled(); - expect( - onEvent.mock.calls.some( - ([event]) => isRecord(event) && event.type === "conversation.item.truncate.skipped", - ), - ).toBe(false); - }); - - it("allows immediate playback barge-in when the minimum audio window is zero", async () => { - const onClearAudio = vi.fn(); - const bridge = createNativeBridge({ - providerConfig: { - apiKey: "sk-test", // pragma: allowlist secret - minBargeInAudioEndMs: 0, - }, - onClearAudio, - }); - const socket = await connectReadyBridge(bridge); - bridge.setMediaTimestamp(1000); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - - expect(onClearAudio).toHaveBeenCalledWith("barge-in"); - expect(parseSent(socket).slice(-2)).toEqual([ - expectedResponseCancelEvent(), - { - type: "conversation.item.truncate", - item_id: "item_1", - content_index: 0, - audio_end_ms: 0, - }, - ]); - }); - - it("drains deferred response.create after a no-active-response cancellation error", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const socket = await connectReadyBridge(bridge); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - - bridge.sendUserMessage?.("queued after cancellation error"); - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - const responseCancelEvent = parseSent(socket).findLast( - (event) => event.type === "response.cancel", - ); - if (!responseCancelEvent?.event_id) { - throw new Error("expected response.cancel event id"); - } - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { - event_id: responseCancelEvent.event_id, - message: "Cancellation failed: no active response found", - }, - }), - ), - ); - - expect(onError).not.toHaveBeenCalled(); - expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); - }); - - it("ignores a stale cancellation error after a newer manual response starts", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const socket = await connectReadyBridge(bridge); - bridge.setMediaTimestamp(1000); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "response.audio.delta", - item_id: "item_1", - delta: Buffer.from("assistant audio").toString("base64"), - }), - ), - ); - bridge.setMediaTimestamp(1300); - - bridge.handleBargeIn?.({ audioPlaybackActive: true }); - const responseCancelEvent = parseSent(socket).findLast( - (event) => event.type === "response.cancel", - ); - if (!responseCancelEvent?.event_id) { - throw new Error("expected response.cancel event id"); - } - bridge.sendUserMessage?.("queued newer response"); - emitServerEvent(socket, { type: "response.done" }); - const sessionUpdateCount = parseSent(socket).filter( - (event) => event.type === "session.update", - ).length; - - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { - event_id: responseCancelEvent.event_id, - message: "Cancellation failed: no active response found", - }, - }), - ), - ); - - expect(onError).not.toHaveBeenCalled(); - expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength( - sessionUpdateCount, - ); - expect(parseSent(socket).at(-1)).toEqual(expectedResponseCreateEvent()); - - emitServerEvent(socket, { type: "response.done" }); - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); - - it("resets deferred response guards after websocket reconnect", async () => { - vi.useFakeTimers(); - const bridge = createNativeBridge(); - const socket = await connectReadyBridge(bridge); - socket.emit( - "message", - Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), - ); - bridge.sendUserMessage?.("queued before reconnect"); - - expect(parseSent(socket).slice(-1)[0]?.type).toBe("conversation.item.create"); - - socket.emit("close", 1006, Buffer.from("transient drop")); - await vi.advanceTimersByTimeAsync(1000); - const reconnectedSocket = requireSocket(1); - openSocket(reconnectedSocket); - emitSessionUpdated(reconnectedSocket); - bridge.sendUserMessage?.("Say hello after reconnect."); - - expect(parseSent(reconnectedSocket).slice(-3)).toEqual([ - { - type: "conversation.item.create", - item: { - type: "message", - role: "user", - content: [{ type: "input_text", text: "Say hello after reconnect." }], - }, - }, - expect.objectContaining({ type: "session.update" }), - expectedResponseCreateEvent(), - ]); - }); - - it("turns active-response errors into a deferred response.create retry", async () => { - const onError = vi.fn(); - const bridge = createNativeBridge({ onError }); - const socket = await connectReadyBridge(bridge); - - bridge.sendUserMessage?.("trigger active-response retry"); - const responseCreateEvent = parseSent(socket).findLast( - (event) => event.type === "response.create", - ); - if (!responseCreateEvent?.event_id) { - throw new Error("expected response.create event id"); - } - socket.emit( - "message", - Buffer.from( - JSON.stringify({ - type: "error", - error: { - event_id: responseCreateEvent.event_id, - message: "Conversation already has an active response in progress: resp_1", - }, - }), - ), - ); - const afterError = parseSent(socket); - expect(afterError.filter((event) => event.type === "session.update")).toHaveLength(2); - expectRecordFields( - requireNestedRecord(afterError.at(-2)?.session, ["audio", "input", "turn_detection"]), - "still suppressed turn detection", - { - create_response: false, - interrupt_response: true, - }, - ); - - emitServerEvent(socket, { type: "response.done" }); - - expect(onError).not.toHaveBeenCalled(); - expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); - - emitServerEvent(socket, { type: "response.done" }); - - expectRecordFields( - requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), - "restored turn detection", - { - create_response: true, - interrupt_response: true, - }, - ); - }); -}); -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/extensions/openai/realtime-voice-provider.ts b/extensions/openai/realtime-voice-provider.ts index e09162f69799..c8c652eba188 100644 --- a/extensions/openai/realtime-voice-provider.ts +++ b/extensions/openai/realtime-voice-provider.ts @@ -1,57 +1,17 @@ -// Openai provider module implements model/runtime integration. -import { execFileSync } from "node:child_process"; -import { randomUUID } from "node:crypto"; import { resolveAgentDir } from "openclaw/plugin-sdk/agent-runtime"; -import { toStringifiedError } from "openclaw/plugin-sdk/error-runtime"; -import { canonicalizeBase64 } from "openclaw/plugin-sdk/media-runtime"; import type { PluginLogger } from "openclaw/plugin-sdk/plugin-entry"; -import { - isProviderAuthProfileConfigured, - resolveProviderAuthProfileApiKey, -} from "openclaw/plugin-sdk/provider-auth"; import { resolveProviderRequestHeaders } from "openclaw/plugin-sdk/provider-http"; -import { - captureWsEvent, - createDebugProxyWebSocketAgent, - resolveDebugProxySettings, -} from "openclaw/plugin-sdk/proxy-capture"; import type { - RealtimeVoiceAudioFormat, - RealtimeVoiceBargeInOptions, - RealtimeVoiceBridge, RealtimeVoiceBrowserSession, RealtimeVoiceBrowserSessionCreateRequest, - RealtimeVoiceBridgeCreateRequest, RealtimeVoiceProviderCapabilities, RealtimeVoiceProviderConfig, RealtimeVoiceProviderPlugin, - RealtimeVoiceSessionConnection, - RealtimeVoiceTool, - RealtimeVoiceToolResultOptions, } from "openclaw/plugin-sdk/realtime-voice"; +import { REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ } from "openclaw/plugin-sdk/realtime-voice"; +import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime"; import { - REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, - REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, - normalizeRealtimeVoiceResponseOutcome, - RealtimeVoiceSessionLifecycle, -} from "openclaw/plugin-sdk/realtime-voice"; -import { sleepWithAbort, warn } from "openclaw/plugin-sdk/runtime-env"; -import { - normalizeResolvedSecretInputString, - normalizeSecretInputString, -} from "openclaw/plugin-sdk/secret-input"; -import { - asFiniteNumber, - asFiniteNumberInRange, - asSafeIntegerInRange, - isRecord, - normalizeOptionalString, -} from "openclaw/plugin-sdk/string-coerce-runtime"; -import WebSocket from "ws"; -import { - captureOpenAIRealtimeWsClose, createOpenAIRealtimeClientSecret, - readRealtimeErrorDetail, resolveOpenAIProviderConfigRecord, } from "./realtime-provider-shared.js"; import { OpenAIQuicksilverVoiceBridge } from "./realtime-quicksilver-bridge.js"; @@ -62,1999 +22,29 @@ import { OPENAI_QUICKSILVER_CAPABILITIES, resolveOpenAIChatGptSubscriptionAuth, } from "./realtime-quicksilver-session.js"; -import { buildOpenAIRealtimeSidebandUrl } from "./realtime-quicksilver-wire.js"; +import { isOpenAIGptLiveModel, isSupportedOpenAIGptLiveModel } from "./realtime-quicksilver.js"; +import { OpenAIRealtimeBridge } from "./realtime-voice-bridge.js"; import { - isOpenAIGptLiveModel, - isSupportedOpenAIGptLiveModel, - OPENAI_GPT_LIVE_MODELS, -} from "./realtime-quicksilver.js"; - -type OpenAIRealtimeVoice = - | "alloy" - | "ash" - | "ballad" - | "cedar" - | "coral" - | "echo" - | "marin" - | "sage" - | "shimmer" - | "verse"; - -type OpenAIRealtimeUserMessageOptions = { - toolChoice?: { type: "function"; name: string }; -}; - -type OpenAIRealtimeVoiceProviderConfig = { - apiKey?: string; - model?: string; - voice?: OpenAIRealtimeVoice; - temperature?: number; - vadThreshold?: number; - silenceDurationMs?: number; - prefixPaddingMs?: number; - interruptResponseOnInputAudio?: boolean; - minBargeInAudioEndMs?: number; - reasoningEffort?: string; - azureEndpoint?: string; - azureDeployment?: string; - azureApiVersion?: string; -}; - -type OpenAIRealtimeVoiceBridgeConfig = RealtimeVoiceBridgeCreateRequest & { - apiKey?: string; - callId?: string; - gaSessionPolicy?: RealtimeGaSessionPolicy; - model?: string; - voice?: OpenAIRealtimeVoice; - temperature?: number; - vadThreshold?: number; - silenceDurationMs?: number; - prefixPaddingMs?: number; - interruptResponseOnInputAudio?: boolean; - minBargeInAudioEndMs?: number; - reasoningEffort?: string; - azureEndpoint?: string; - azureDeployment?: string; - azureApiVersion?: string; -}; - -const OPENAI_REALTIME_DEFAULT_MODEL = "gpt-realtime-2.1"; -// Picker suggestions surfaced through talk.catalog; each value is live-verified -// against the OpenAI realtime APIs. Free-form model values are still accepted. -const OPENAI_REALTIME_MODELS = [ - "gpt-realtime-2.1", - "gpt-realtime-2.1-mini", - "gpt-realtime-2", - ...OPENAI_GPT_LIVE_MODELS, -] as const; -const OPENAI_REALTIME_INPUT_TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe"; -const OPENAI_REALTIME_CAPABILITIES: RealtimeVoiceProviderCapabilities = { - transports: ["webrtc", "gateway-relay"], - inputAudioFormats: [ - REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, - REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, - ], - outputAudioFormats: [ - REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, - REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, - ], - supportsBrowserSession: true, - supportsBargeIn: true, - handlesInputAudioBargeIn: true, - supportsToolCalls: true, - supportsVideoFrames: true, -}; -const OPENAI_REALTIME_ACTIVE_RESPONSE_ERROR_PREFIX = - "Conversation already has an active response in progress:"; -const OPENAI_REALTIME_NO_ACTIVE_RESPONSE_CANCEL_ERROR = - "Cancellation failed: no active response found"; -const OPENAI_REALTIME_MAX_SESSION_DURATION_FRAGMENT = "maximum duration"; -const OPENAI_VOICE_WS_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024; -const OPENAI_REALTIME_SIDEBAND_STARTUP_MAX_BYTES = 1024 * 1024; -const OPENAI_REALTIME_DEFAULT_MIN_BARGE_IN_AUDIO_END_MS = 250; -// Realtime validates this character set but accepts names beyond the 64-character -// cap used by other OpenAI tool surfaces. -const OPENAI_REALTIME_TOOL_NAME_RE = /^[A-Za-z0-9_-]+$/; -const AZURE_OPENAI_REALTIME_TOOL_NAME_MAX_LENGTH = 64; -const OPENAI_REALTIME_VOICES = [ - "alloy", - "ash", - "ballad", - "coral", - "echo", - "sage", - "shimmer", - "verse", - "marin", - "cedar", -] as const satisfies readonly OpenAIRealtimeVoice[]; - -function normalizeOpenAIRealtimeVoice(value: unknown): OpenAIRealtimeVoice | undefined { - if (typeof value !== "string") { - return undefined; - } - const normalized = value.trim().toLowerCase(); - return OPENAI_REALTIME_VOICES.includes(normalized as OpenAIRealtimeVoice) - ? (normalized as OpenAIRealtimeVoice) - : undefined; -} - -type RealtimeEvent = { - type: string; - delta?: string; - data?: string; - text?: string; - transcript?: string; - item_id?: string; - response_id?: string; - call_id?: string; - name?: string; - arguments?: string; - session?: unknown; - item?: { - id?: string; - type?: string; - name?: string; - call_id?: string; - arguments?: string; - }; - response?: { - id?: string; - status?: string; - status_details?: unknown; - output?: unknown[]; - }; - error?: unknown; -}; - -type RealtimeTurnDetectionConfig = { - type: "server_vad"; - threshold: number; - prefix_padding_ms: number; - silence_duration_ms: number; - create_response: boolean; - interrupt_response?: boolean; -}; - -type RealtimeGaSessionPolicy = { - type: "realtime"; - model: string; - instructions?: string; - output_modalities: string[]; - audio: { - input: { - format: OpenAIRealtimeAudioFormatConfig; - turn_detection: RealtimeTurnDetectionConfig; - noise_reduction: { type: "near_field" } | null; - transcription: { model: string; language?: string }; - }; - output: { - format: OpenAIRealtimeAudioFormatConfig; - voice: OpenAIRealtimeVoice; - }; - }; - reasoning?: { effort: string }; - tools?: RealtimeVoiceTool[]; - tool_choice?: string; -}; - -type RealtimeGaSessionUpdate = { - type: "session.update"; - session: RealtimeGaSessionPolicy; -}; - -type RealtimeAzureDeploymentSessionUpdate = { - type: "session.update"; - session: { - modalities: string[]; - instructions?: string; - voice: OpenAIRealtimeVoice; - input_audio_format: "g711_ulaw" | "pcm16"; - output_audio_format: "g711_ulaw" | "pcm16"; - input_audio_transcription?: { model: string; language?: string }; - turn_detection: RealtimeTurnDetectionConfig; - temperature: number; - tools?: RealtimeVoiceTool[]; - tool_choice?: string; - }; -}; - -type OpenAIRealtimeAudioFormatConfig = - | { - type: "audio/pcm"; - rate: 24000; - } - | { - type: "audio/pcmu"; - }; - -function normalizeProviderConfig( - config: RealtimeVoiceProviderConfig, -): OpenAIRealtimeVoiceProviderConfig { - const raw = resolveOpenAIProviderConfigRecord(config); - return { - apiKey: normalizeResolvedSecretInputString({ - value: raw?.apiKey, - path: "plugins.entries.voice-call.config.realtime.providers.openai.apiKey", - }), - model: normalizeOptionalString(raw?.model), - voice: normalizeOpenAIRealtimeVoice(raw?.speakerVoice ?? raw?.voice), - temperature: asFiniteNumber(raw?.temperature), - vadThreshold: asUnitInterval(raw?.vadThreshold), - silenceDurationMs: asNonNegativeInteger(raw?.silenceDurationMs), - prefixPaddingMs: asNonNegativeInteger(raw?.prefixPaddingMs), - interruptResponseOnInputAudio: - typeof raw?.interruptResponseOnInputAudio === "boolean" - ? raw.interruptResponseOnInputAudio - : undefined, - minBargeInAudioEndMs: asNonNegativeInteger(raw?.minBargeInAudioEndMs), - reasoningEffort: normalizeOptionalString(raw?.reasoningEffort), - azureEndpoint: normalizeOptionalString(raw?.azureEndpoint), - azureDeployment: normalizeOptionalString(raw?.azureDeployment), - azureApiVersion: normalizeOptionalString(raw?.azureApiVersion), - }; -} - -function asNonNegativeInteger(value: unknown): number | undefined { - return asSafeIntegerInRange(value, { min: 0 }); -} - -function asUnitInterval(value: unknown): number | undefined { - return asFiniteNumberInRange(value, { min: 0, max: 1 }); -} - -type OpenAIRealtimeApiKeyResolution = - | { status: "available"; value: string } - | { status: "missing" }; - -const OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED = - "OpenAI Realtime voice requires an OpenAI Platform API key"; -const OPENAI_GPT_LIVE_AUTH_REQUIRED = - "GPT-Live Talk requires either an OpenAI Platform API key or a ChatGPT OAuth subscription profile"; -const OPENAI_GPT_LIVE_AUTHORED_PLATFORM_AUTH_UNAVAILABLE = - "GPT-Live Talk requires a working OpenAI Platform API key or ChatGPT OAuth subscription profile. The selected Platform API-key source could not be resolved, so OAuth fallback was not used; fix or remove it."; -const OPENAI_REALTIME_API_KEY_REQUIRED = "OpenAI Realtime voice requires an API key"; -const OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED = - "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source"; -const KEYCHAIN_SECRET_REF_RE = /^keychain:([^:]+):([^:]+)$/; -const KEYCHAIN_LOOKUP_TIMEOUT_MS = 5000; -const resolvedKeychainSecretRefCache = new Map(); - -function isDirectOpenAIRealtimeWebSocketUrl(value: string): boolean { - try { - return new URL(value).hostname === "api.openai.com"; - } catch { - return false; - } -} - -function isOpenAIRealtimeStartupAuthFailure(error: unknown): boolean { - const record = - typeof error === "object" && error !== null ? (error as Record) : undefined; - const status = record?.status ?? record?.statusCode; - const rawCode = record?.code ?? record?.errorCode; - const code = typeof rawCode === "string" ? rawCode.toLowerCase() : ""; - const message = readRealtimeErrorDetail(error).toLowerCase(); - return ( - status === 401 || - code === "invalid_api_key" || - message.includes("invalid_api_key") || - message.includes("incorrect api key provided") || - message.includes("unexpected server response: 401") - ); -} - -function resolveKeychainSecretRef(value: string): string | undefined { - const trimmed = value.trim(); - const match = KEYCHAIN_SECRET_REF_RE.exec(trimmed); - if (!match) { - return trimmed || undefined; - } - const cached = resolvedKeychainSecretRefCache.get(trimmed); - if (cached) { - return cached; - } - const [, service, account] = match; - if (!service || !account) { - return undefined; - } - try { - const resolved = - execFileSync( - "/usr/bin/security", - ["find-generic-password", "-s", service, "-a", account, "-w"], - { - encoding: "utf8", - stdio: ["ignore", "pipe", "pipe"], - timeout: KEYCHAIN_LOOKUP_TIMEOUT_MS, - }, - ).trim() || undefined; - if (resolved) { - resolvedKeychainSecretRefCache.set(trimmed, resolved); - } - return resolved; - } catch { - return undefined; - } -} - -function resolveOpenAIRealtimeSecretInput( - configuredApiKey: string | undefined, -): OpenAIRealtimeApiKeyResolution { - const configured = normalizeSecretInputString(configuredApiKey); - if (configured) { - const value = resolveKeychainSecretRef(configured); - return value ? { status: "available", value } : { status: "missing" }; - } - - return { status: "missing" }; -} - -function resolveOpenAIRealtimeEnvApiKey(): OpenAIRealtimeApiKeyResolution { - const envValue = normalizeSecretInputString(process.env.OPENAI_API_KEY); - if (!envValue) { - return { status: "missing" }; - } - const value = resolveKeychainSecretRef(envValue); - return value ? { status: "available", value } : { status: "missing" }; -} - -function resolveOpenAIRealtimeApiKey( - configuredApiKey: string | undefined, -): OpenAIRealtimeApiKeyResolution { - const configured = resolveOpenAIRealtimeSecretInput(configuredApiKey); - if ( - configured.status === "available" || - hasOpenAIRealtimeConfiguredApiKeyInput(configuredApiKey) - ) { - return configured; - } - return resolveOpenAIRealtimeEnvApiKey(); -} - -function requireOpenAIRealtimeApiKey( - configuredApiKey: string | undefined, - errorMessage = OPENAI_REALTIME_API_KEY_REQUIRED, -): string { - const resolved = resolveOpenAIRealtimeApiKey(configuredApiKey); - if (resolved.status === "available") { - return resolved.value; - } - throw new Error(errorMessage); -} - -function hasOpenAIRealtimeConfiguredApiKeyInput(configuredApiKey: string | undefined): boolean { - return Boolean(normalizeSecretInputString(configuredApiKey)); -} - -function hasOpenAIRealtimeApiKeyInput(configuredApiKey: string | undefined): boolean { - return Boolean( - normalizeSecretInputString(configuredApiKey) ?? - normalizeSecretInputString(process.env.OPENAI_API_KEY), - ); -} - -function normalizeOpenAIRealtimeTools( - tools: RealtimeVoiceTool[] | undefined, - maxNameLength?: number, -): RealtimeVoiceTool[] | undefined { - const normalized: RealtimeVoiceTool[] = []; - let omitted = 0; - for (const tool of tools ?? []) { - try { - const name = tool.name; - if (typeof name !== "string") { - omitted += 1; - continue; - } - const exceedsLengthLimit = maxNameLength !== undefined && name.length > maxNameLength; - if (exceedsLengthLimit || !OPENAI_REALTIME_TOOL_NAME_RE.test(name)) { - omitted += 1; - continue; - } - normalized.push({ - type: "function", - name, - description: tool.description, - parameters: tool.parameters, - }); - } catch { - omitted += 1; - } - } - if (omitted > 0) { - warn(`openai realtime: omitted ${omitted} tool definition(s) with unsupported names`); - } - return normalized.length > 0 ? normalized : undefined; -} - -function resolveOpenAIRealtimeAudioFormat( - audioFormat: RealtimeVoiceAudioFormat = REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, -): OpenAIRealtimeAudioFormatConfig { - return audioFormat.encoding === "pcm16" - ? { type: "audio/pcm", rate: 24000 } - : { type: "audio/pcmu" }; -} - -function buildOpenAIRealtimeTurnDetectionConfig(params: { - autoRespondToAudio?: boolean; - createResponse?: boolean; - includeInterruptResponse?: boolean; - interruptResponseOnInputAudio?: boolean; - prefixPaddingMs?: number; - silenceDurationMs?: number; - vadThreshold?: number; -}): RealtimeTurnDetectionConfig { - const configuredAutoResponse = params.autoRespondToAudio ?? true; - return { - type: "server_vad", - threshold: params.vadThreshold ?? 0.5, - prefix_padding_ms: params.prefixPaddingMs ?? 300, - silence_duration_ms: params.silenceDurationMs ?? 500, - create_response: params.createResponse ?? configuredAutoResponse, - ...(params.includeInterruptResponse - ? { - interrupt_response: params.interruptResponseOnInputAudio ?? configuredAutoResponse, - } - : {}), - }; -} - -function buildOpenAIRealtimeGaSessionPolicy(params: { - audioFormat?: RealtimeVoiceAudioFormat; - autoRespondToAudio?: boolean; - instructions?: string; - interruptResponseOnInputAudio?: boolean; - language?: string; - model: string; - noiseReduction: { type: "near_field" } | null; - prefixPaddingMs?: number; - reasoningEffort?: string; - silenceDurationMs?: number; - tools?: RealtimeVoiceTool[]; - vadThreshold?: number; - voice: OpenAIRealtimeVoice; -}): RealtimeGaSessionPolicy { - const format = resolveOpenAIRealtimeAudioFormat(params.audioFormat); - return { - type: "realtime", - model: params.model, - ...(params.instructions !== undefined ? { instructions: params.instructions } : {}), - output_modalities: ["audio"], - audio: { - input: { - format, - noise_reduction: params.noiseReduction, - transcription: { - model: OPENAI_REALTIME_INPUT_TRANSCRIPTION_MODEL, - ...(params.language ? { language: params.language } : {}), - }, - turn_detection: buildOpenAIRealtimeTurnDetectionConfig({ - autoRespondToAudio: params.autoRespondToAudio, - includeInterruptResponse: true, - interruptResponseOnInputAudio: params.interruptResponseOnInputAudio, - prefixPaddingMs: params.prefixPaddingMs, - silenceDurationMs: params.silenceDurationMs, - vadThreshold: params.vadThreshold, - }), - }, - output: { - format, - voice: params.voice, - }, - }, - ...(params.reasoningEffort ? { reasoning: { effort: params.reasoningEffort } } : {}), - ...(params.tools ? { tools: params.tools, tool_choice: "auto" } : {}), - }; -} - -async function resolveOpenAIRealtimePlatformAuth(params: { - configuredApiKey: string | undefined; - cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; -}): Promise { - const configured = resolveOpenAIRealtimeSecretInput(params.configuredApiKey); - if ( - configured.status === "available" || - hasOpenAIRealtimeConfiguredApiKeyInput(params.configuredApiKey) - ) { - return configured; - } - - const profileApiKey = await resolveProviderAuthProfileApiKey({ - provider: "openai", - cfg: params.cfg, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }); - if (profileApiKey) { - return { status: "available", value: profileApiKey }; - } - const hasConfiguredApiKeyProfile = isProviderAuthProfileConfigured({ - provider: "openai", - cfg: params.cfg, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }); - - const envApiKey = resolveOpenAIRealtimeEnvApiKey(); - if (envApiKey.status === "available") { - return envApiKey; - } - if (hasConfiguredApiKeyProfile || hasOpenAIRealtimeApiKeyInput(undefined)) { - return { status: "missing" }; - } - - return { status: "missing" }; -} - -async function requireOpenAIRealtimePlatformAuth(params: { - configuredApiKey: string | undefined; - cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; -}): Promise> { - const resolved = await resolveOpenAIRealtimePlatformAuth(params); - if (resolved.status === "available") { - return resolved; - } - throw new Error(OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED); -} - -async function resolveOpenAIQuicksilverBridgeAuth(params: { - configuredApiKey: string | undefined; - cfg: RealtimeVoiceBridgeCreateRequest["cfg"] | undefined; - agentId?: string; -}) { - const subscriptionAuth = await resolveOpenAIChatGptSubscriptionAuth({ - cfg: params.cfg, - agentDir: - params.cfg && params.agentId ? resolveAgentDir(params.cfg, params.agentId) : undefined, - }); - if (subscriptionAuth) { - return subscriptionAuth; - } - const platformAuth = await resolveOpenAIRealtimePlatformAuth(params); - if (platformAuth.status === "available") { - return { type: "api-key" as const, token: platformAuth.value }; - } - if ( - hasOpenAIRealtimePlatformAuthInput({ - configuredApiKey: params.configuredApiKey, - cfg: params.cfg, - }) - ) { - throw new Error(OPENAI_GPT_LIVE_AUTHORED_PLATFORM_AUTH_UNAVAILABLE); - } - throw new Error(OPENAI_GPT_LIVE_AUTH_REQUIRED); -} - -function hasOpenAIRealtimePlatformAuthInput(params: { - configuredApiKey: string | undefined; - cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; -}): boolean { - if (hasOpenAIRealtimeConfiguredApiKeyInput(params.configuredApiKey)) { - return true; - } - if ( - isProviderAuthProfileConfigured({ - provider: "openai", - cfg: params.cfg, - profileTypes: ["api_key"], - includeExternalCliAuth: false, - }) - ) { - return true; - } - return hasOpenAIRealtimeApiKeyInput(undefined); -} - -function hasOpenAIChatGptSubscriptionAuthInput(params: { - cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; - agentId?: string; -}): boolean { - return isProviderAuthProfileConfigured({ - provider: "openai", - cfg: params.cfg, - agentDir: - params.cfg && params.agentId ? resolveAgentDir(params.cfg, params.agentId) : undefined, - profileTypes: ["oauth"], - includeExternalCliAuth: false, - }); -} - -function isOpenAIRealtimeMaxSessionDurationError(detail: string): boolean { - const normalized = detail.toLowerCase(); - return ( - normalized.includes("session") && - normalized.includes(OPENAI_REALTIME_MAX_SESSION_DURATION_FRAGMENT) - ); -} - -function readRealtimeErrorEventId(error: unknown): string | undefined { - if (!error || typeof error !== "object") { - return undefined; - } - const eventId = (error as Record).event_id; - return typeof eventId === "string" ? eventId : undefined; -} - -function parsePlaybackMarkSequence(markName: string): number | undefined { - const match = /^audio-(\d+)$/u.exec(markName); - if (!match) { - return undefined; - } - const sequence = Number(match[1]); - return Number.isSafeInteger(sequence) && sequence > 0 ? sequence : undefined; -} - -class OpenAIRealtimeMalformedAudioError extends Error {} - -function base64ToBuffer(b64: string): Buffer { - const canonicalAudio = canonicalizeBase64(b64); - if (!canonicalAudio) { - throw new OpenAIRealtimeMalformedAudioError( - "OpenAI realtime stream returned malformed base64 audio data", - ); - } - return Buffer.from(canonicalAudio, "base64"); -} - -class OpenAIRealtimeVoiceBridge implements RealtimeVoiceBridge { - private static readonly DEFAULT_MODEL = OPENAI_REALTIME_DEFAULT_MODEL; - private static readonly MAX_RECONNECT_ATTEMPTS = 5; - private static readonly BASE_RECONNECT_DELAY_MS = 1000; - private static readonly CONNECT_TIMEOUT_MS = 10_000; - private static readonly MAX_TOOL_ARGUMENT_BYTES = 256_000; - // Realtime defines no replay window. Keep every terminal id for this - // connection generation, then fail instead of re-admitting late duplicates. - private static readonly MAX_COMPLETED_TOOL_CALL_IDS = 1_024; - readonly supportsToolResultContinuation = true; - readonly supportsToolResultSuppression = true; - - private ws: WebSocket | null = null; - private readonly lifecycle = new RealtimeVoiceSessionLifecycle("OpenAI"); - private nextMarkSequence = 1; - private oldestOutstandingMarkSequence: number | null = null; - private latestOutstandingMarkSequence: number | null = null; - private responseStartTimestamp: number | null = null; - private responseActive = false; - private responseCreateInFlight = false; - private manualResponseCreateEventId: string | null = null; - private responseCancelInFlight = false; - private manualResponseCancelEventId: string | null = null; - private responseCreatePending = false; - private autoRespondSuppressedForManualResponse = false; - private continuingToolCallIds = new Set(); - private pendingToolCallIds = new Set(); - private latestMediaTimestamp = 0; - private lastAssistantItemId: string | null = null; - private connectionUrl = ""; - private completedToolCallIds = new Set(); - private standaloneSpeechQueue: string[] = []; - private standaloneSpeechActive = false; - private standaloneSpeechEventId: string | null = null; - private readonly flowId = randomUUID(); - private sessionReadyFired = false; - private reconnectReason: string | undefined; - private activeConnectionReason: string | undefined; - private terminalError: Error | undefined; - private readonly audioFormat: RealtimeVoiceAudioFormat; - - constructor(private readonly config: OpenAIRealtimeVoiceBridgeConfig) { - this.audioFormat = config.audioFormat ?? REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ; - } - - async connect(): Promise { - if (this.terminalError) { - throw this.terminalError; - } - await this.lifecycle.connect((connection) => this.doConnect(connection)); - } - - sendAudio(audio: Buffer): void { - if (this.lifecycle.phase() === "terminal") { - return; - } - if (!this.lifecycle.isReady() || this.ws?.readyState !== WebSocket.OPEN) { - this.lifecycle.enqueuePendingAudio(audio); - return; - } - this.sendEvent({ - type: "input_audio_buffer.append", - audio: audio.toString("base64"), - }); - } - - setMediaTimestamp(ts: number): void { - this.latestMediaTimestamp = ts; - } - - sendUserMessage(text: string, options?: OpenAIRealtimeUserMessageOptions): void { - if ( - options?.toolChoice && - (this.responseActive || - this.responseCreateInFlight || - this.responseCancelInFlight || - this.pendingToolCallIds.size > 0) - ) { - throw new Error("Forced realtime tool choice requires an idle response state"); - } - if (this.pendingToolCallIds.size > 0) { - // Control/status speech must not wait behind the long-running consult whose - // function output owns the default conversation response. - this.standaloneSpeechQueue.push(text); - this.flushStandaloneSpeech(); - return; - } - this.sendEvent({ - type: "conversation.item.create", - item: { - type: "message", - role: "user", - content: [{ type: "input_text", text }], - }, - }); - this.requestResponseCreate(options); - } - - triggerGreeting(instructions?: string): void { - if (!this.isConnected() || !this.ws) { - return; - } - this.sendUserMessage(instructions ?? this.config.instructions ?? "Greet the meeting."); - } - - submitToolResult( - callId: string, - result: unknown, - options?: RealtimeVoiceToolResultOptions, - ): void { - if (this.lifecycle.phase() === "terminal" || !this.pendingToolCallIds.has(callId)) { - return; - } - const output = JSON.stringify(result); - if (typeof output !== "string") { - throw new Error("OpenAI realtime voice tool result is not JSON-serializable"); - } - this.sendEvent({ - type: "conversation.item.create", - item: { - type: "function_call_output", - call_id: callId, - output, - }, - }); - if (options?.willContinue === true) { - this.continuingToolCallIds.add(callId); - return; - } - this.continuingToolCallIds.delete(callId); - this.pendingToolCallIds.delete(callId); - if (options?.suppressResponse === true) { - this.flushPendingResponseCreate(); - return; - } - this.requestResponseCreate(); - } - - acknowledgeMark(markName?: string): void { - const oldest = this.oldestOutstandingMarkSequence; - const latest = this.latestOutstandingMarkSequence; - if (oldest === null || latest === null) { - return; - } - const acknowledgedSequence = - markName === undefined ? oldest : parsePlaybackMarkSequence(markName); - if ( - acknowledgedSequence === undefined || - acknowledgedSequence < oldest || - acknowledgedSequence > latest - ) { - return; - } - // Marks follow ordered playback. Reaching a named mark also acknowledges every - // earlier mark, while late acknowledgements from that prefix remain harmless. - if (acknowledgedSequence === latest) { - this.oldestOutstandingMarkSequence = null; - this.latestOutstandingMarkSequence = null; - return; - } - this.oldestOutstandingMarkSequence = acknowledgedSequence + 1; - } - - close(): void { - const connection = this.lifecycle.currentConnection(); - if (!this.lifecycle.cancel()) { - return; - } - this.resetTerminalState(); - if (!connection) { - return; - } - const ws = this.ws; - this.ws = null; - ws?.close(1000, "Bridge closed"); - this.notifyClose(connection, "completed"); - } - - isConnected(): boolean { - return this.lifecycle.isReady() && this.ws?.readyState === WebSocket.OPEN; - } - - private async doConnect(lifecycleConnection: RealtimeVoiceSessionConnection): Promise { - let activeWs: WebSocket | undefined; - let startupFrameBytes = 0; - const attempt = this.lifecycle.createConnectAttempt({ - connection: lifecycleConnection, - timeoutMs: OpenAIRealtimeVoiceBridge.CONNECT_TIMEOUT_MS, - timeoutError: () => new Error("OpenAI realtime connection timeout"), - onTimeout: () => activeWs?.terminate(), - onAbort: () => { - if (activeWs && activeWs.readyState !== WebSocket.CLOSED) { - activeWs.close(1000, "connection canceled"); - } - }, - }); - - const openWebSocket = (resolvedConnection: { - url: string; - headers: Record; - }) => { - if (attempt.settled) { - return; - } - if (!this.lifecycle.isCurrent(lifecycleConnection) || lifecycleConnection.signal.aborted) { - attempt.resolve(); - return; - } - // Auth preparation owns its own timeout. Start the socket deadline only - // after connection parameters are available. - attempt.startTimeout(); - const url = resolvedConnection.url; - this.connectionUrl = resolvedConnection.url; - const debugProxy = resolveDebugProxySettings(); - const proxyAgent = createDebugProxyWebSocketAgent(debugProxy); - const ws = new WebSocket(resolvedConnection.url, { - headers: resolvedConnection.headers, - maxPayload: OPENAI_VOICE_WS_MAX_PAYLOAD_BYTES, - ...(proxyAgent ? { agent: proxyAgent } : {}), - }); - activeWs = ws; - this.ws = ws; - - const rejectStartup = (error: Error) => { - if (!attempt.rejectStartup(error)) { - return; - } - if (ws.readyState !== WebSocket.CLOSED) { - ws.close(1000, "startup failed"); - } - }; - - ws.on("open", () => { - if (!this.lifecycle.acceptsEvents(lifecycleConnection)) { - ws.close(1000, "stale connection"); - return; - } - this.resetRealtimeSessionState(); - captureWsEvent({ - url, - direction: "local", - kind: "ws-open", - flowId: this.flowId, - meta: { - provider: "openai", - capability: "realtime-voice", - }, - }); - this.sendSessionUpdate(); - }); - - ws.on("message", (data: Buffer) => { - if (!this.lifecycle.acceptsEvents(lifecycleConnection) || this.ws !== ws) { - return; - } - if (attempt.settled && !attempt.ready) { - return; - } - if (!attempt.ready) { - startupFrameBytes += data.byteLength; - if (startupFrameBytes > OPENAI_REALTIME_SIDEBAND_STARTUP_MAX_BYTES) { - const error = new Error("OpenAI realtime sideband startup buffer exceeded"); - attempt.reject(error); - this.failConnection(error, ws, lifecycleConnection, { - code: 1009, - reason: "Sideband startup buffer exceeded", - }); - return; - } - } - captureWsEvent({ - url, - direction: "inbound", - kind: "ws-frame", - flowId: this.flowId, - payload: data, - meta: { - provider: "openai", - capability: "realtime-voice", - }, - }); - try { - const event = JSON.parse(data.toString()) as RealtimeEvent; - if (event.type === "error" && !attempt.ready) { - // Only direct OpenAI auth failures get bounded remediation. Azure, - // custom endpoints, and non-auth startup details remain provider-owned. - rejectStartup( - isDirectOpenAIRealtimeWebSocketUrl(url) && - isOpenAIRealtimeStartupAuthFailure(event.error) - ? new Error(OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED) - : new Error(readRealtimeErrorDetail(event.error)), - ); - return; - } - if (event.type === "session.updated") { - try { - this.handleEvent(event, lifecycleConnection); - } catch (error) { - const readyError = toStringifiedError(error); - attempt.reject(readyError); - this.failConnection(readyError, ws, lifecycleConnection, { - code: 1011, - reason: "Readiness callback failed", - }); - return; - } - attempt.resolve(this.lifecycle.isReady()); - return; - } - this.handleEvent(event, lifecycleConnection); - } catch (error) { - if (error instanceof OpenAIRealtimeMalformedAudioError) { - attempt.reject(error); - this.failConnection(error, ws, lifecycleConnection, { - code: 1002, - reason: "Malformed audio payload", - }); - return; - } - console.error("[openai] realtime event parse failed:", error); - } - }); - - ws.on("error", (error) => { - if (!this.lifecycle.acceptsEvents(lifecycleConnection) || this.ws !== ws) { - return; - } - captureWsEvent({ - url, - direction: "local", - kind: "error", - flowId: this.flowId, - errorText: error instanceof Error ? error.message : String(error), - meta: { - provider: "openai", - capability: "realtime-voice", - }, - }); - if (!attempt.ready) { - const startupError = toStringifiedError(error); - rejectStartup( - isDirectOpenAIRealtimeWebSocketUrl(url) && - isOpenAIRealtimeStartupAuthFailure(startupError) - ? new Error(OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED) - : startupError, - ); - return; - } - this.config.onError?.(toStringifiedError(error)); - }); - - ws.on("close", (code, reasonBuffer) => { - captureOpenAIRealtimeWsClose({ - url, - flowId: this.flowId, - capability: "realtime-voice", - code, - reasonBuffer, - }); - if (!this.lifecycle.isCurrent(lifecycleConnection)) { - return; - } - if (this.ws === ws) { - this.ws = null; - } - if (attempt.startupFailed) { - return; - } - if (this.terminalError) { - this.notifyClose(lifecycleConnection, "error"); - return; - } - if (this.lifecycle.terminalOutcome(lifecycleConnection) === "completed") { - attempt.resolve(); - this.notifyClose(lifecycleConnection, "completed"); - return; - } - if (!attempt.ready && !attempt.settled) { - const error = new Error("OpenAI realtime connection closed before ready"); - attempt.reject(error); - return; - } - const reason = this.reconnectReason ?? "websocket-close"; - this.reconnectReason = undefined; - void this.attemptReconnect(reason, lifecycleConnection); - }); - }; - - let connectionOrPromise: - | { url: string; headers: Record } - | Promise<{ url: string; headers: Record }>; - try { - connectionOrPromise = this.resolveConnectionParams(); - } catch (error) { - attempt.reject(toStringifiedError(error)); - return attempt.promise; - } - if (connectionOrPromise instanceof Promise) { - void connectionOrPromise.then(openWebSocket).catch((error: unknown) => { - if ( - !this.lifecycle.isCurrent(lifecycleConnection) || - this.lifecycle.terminalOutcome(lifecycleConnection) === "completed" - ) { - attempt.resolve(); - return; - } - attempt.reject(toStringifiedError(error)); - }); - } else { - try { - openWebSocket(connectionOrPromise); - } catch (error) { - attempt.reject(toStringifiedError(error)); - } - } - await attempt.promise; - } - - private resolveConnectionParams(): - | { url: string; headers: Record } - | Promise<{ url: string; headers: Record }> { - const cfg = this.config; - const model = cfg.model ?? OpenAIRealtimeVoiceBridge.DEFAULT_MODEL; - if (cfg.azureEndpoint && cfg.azureDeployment) { - const apiKey = requireOpenAIRealtimeApiKey(cfg.apiKey); - const base = cfg.azureEndpoint - .replace(/\/$/, "") - .replace(/^http(s?):/, (_, secure: string) => `ws${secure}:`); - const apiVersion = cfg.azureApiVersion ?? "2024-10-01-preview"; - const url = `${base}/openai/realtime?api-version=${apiVersion}&deployment=${encodeURIComponent( - cfg.azureDeployment, - )}`; - return { - url, - headers: resolveProviderRequestHeaders({ - provider: "openai", - baseUrl: url, - capability: "audio", - transport: "websocket", - defaultHeaders: { "api-key": apiKey }, - }) ?? { "api-key": apiKey }, - }; - } - - if (hasOpenAIRealtimeConfiguredApiKeyInput(cfg.apiKey)) { - const directApiKey = resolveOpenAIRealtimeSecretInput(cfg.apiKey); - if (directApiKey.status === "missing") { - throw new Error(OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED); - } - return this.resolveApiKeyConnectionParams(directApiKey.value, model); - } - - if (cfg.azureEndpoint) { - const directApiKey = resolveOpenAIRealtimeEnvApiKey(); - if (directApiKey.status === "missing") { - throw new Error(OPENAI_REALTIME_API_KEY_REQUIRED); - } - return this.resolveApiKeyConnectionParams(directApiKey.value, model); - } - - return this.resolveDefaultConnectionParams(model); - } - - private async resolveDefaultConnectionParams(model: string): Promise<{ - url: string; - headers: Record; - }> { - const auth = await requireOpenAIRealtimePlatformAuth({ - configuredApiKey: this.config.apiKey, - cfg: this.config.cfg, - }); - return this.resolveApiKeyConnectionParams(auth.value, model); - } - - private resolveApiKeyConnectionParams( - apiKey: string, - model: string, - ): { url: string; headers: Record } { - const cfg = this.config; - if (cfg.azureEndpoint) { - const base = cfg.azureEndpoint - .replace(/\/$/, "") - .replace(/^http(s?):/, (_, secure: string) => `ws${secure}:`); - const url = `${base}/v1/realtime?model=${encodeURIComponent(model)}`; - return { - url, - headers: resolveProviderRequestHeaders({ - provider: "openai", - baseUrl: url, - capability: "audio", - transport: "websocket", - defaultHeaders: { Authorization: `Bearer ${apiKey}` }, - }) ?? { Authorization: `Bearer ${apiKey}` }, - }; - } - - const url = cfg.callId - ? buildOpenAIRealtimeSidebandUrl(cfg.callId) - : `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(model)}`; - return { - url, - headers: resolveProviderRequestHeaders({ - provider: "openai", - baseUrl: url, - capability: "audio", - transport: "websocket", - defaultHeaders: { - Authorization: `Bearer ${apiKey}`, - }, - }) ?? { - Authorization: `Bearer ${apiKey}`, - }, - }; - } - - private async attemptReconnect( - reason: string, - connection: RealtimeVoiceSessionConnection, - ): Promise { - const retry = this.lifecycle.retry( - connection, - OpenAIRealtimeVoiceBridge.MAX_RECONNECT_ATTEMPTS, - ); - if (!retry) { - return; - } - if (retry === "exhausted") { - this.config.onEvent?.({ - direction: "client", - type: "session.reconnect.exhausted", - detail: `reason=${reason} attempts=${OpenAIRealtimeVoiceBridge.MAX_RECONNECT_ATTEMPTS}`, - }); - if (this.lifecycle.failure(connection)) { - this.resetTerminalState(); - } - this.notifyClose(connection, "error"); - return; - } - const attempt = retry.attempt; - const delay = OpenAIRealtimeVoiceBridge.BASE_RECONNECT_DELAY_MS * 2 ** (attempt - 1); - if (attempt === 1) { - // OpenAI reconnects start a fresh provider generation. Reset consumers - // before backoff so stale async work cannot satisfy reused call ids. - this.resetRealtimeSessionState(); - this.config.onEvent?.({ - direction: "client", - type: "session.continuity.reset", - }); - } - this.config.onEvent?.({ - direction: "client", - type: "session.reconnect.scheduled", - detail: `reason=${reason} attempt=${attempt} delayMs=${delay}`, - }); - try { - await sleepWithAbort(delay, retry.signal); - } catch (error) { - if (!retry.signal.aborted) { - throw error; - } - return; - } - const nextConnection = this.lifecycle.reconnect(connection); - if (!nextConnection) { - return; - } - try { - await this.doConnect(nextConnection); - if (!this.lifecycle.isCurrent(nextConnection) || !this.lifecycle.isReady()) { - return; - } - this.config.onEvent?.({ - direction: "client", - type: "session.reconnect.ready", - detail: `reason=${reason} attempt=${attempt}`, - }); - } catch (error) { - if (!this.lifecycle.acceptsEvents(nextConnection)) { - return; - } - this.config.onError?.(toStringifiedError(error)); - await this.attemptReconnect(reason, nextConnection); - } - } - - private sendSessionUpdate(): void { - if (this.usesAzureDeploymentRealtimeApi()) { - this.sendEvent(this.buildAzureDeploymentSessionUpdate()); - return; - } - - this.sendEvent(this.buildGaSessionUpdate()); - } - - private buildGaSessionUpdate(): RealtimeGaSessionUpdate { - const cfg = this.config; - return { - type: "session.update", - session: - cfg.gaSessionPolicy ?? - buildOpenAIRealtimeGaSessionPolicy({ - audioFormat: this.audioFormat, - autoRespondToAudio: cfg.autoRespondToAudio, - instructions: cfg.instructions, - interruptResponseOnInputAudio: cfg.interruptResponseOnInputAudio, - language: cfg.language, - model: cfg.model ?? OpenAIRealtimeVoiceBridge.DEFAULT_MODEL, - noiseReduction: null, - prefixPaddingMs: cfg.prefixPaddingMs, - reasoningEffort: cfg.reasoningEffort, - silenceDurationMs: cfg.silenceDurationMs, - tools: normalizeOpenAIRealtimeTools(cfg.tools), - vadThreshold: cfg.vadThreshold, - voice: cfg.voice ?? "alloy", - }), - }; - } - - private usesAzureDeploymentRealtimeApi(): boolean { - return Boolean(this.config.azureEndpoint && this.config.azureDeployment); - } - - private buildAzureDeploymentSessionUpdate(): RealtimeAzureDeploymentSessionUpdate { - const cfg = this.config; - const format = this.resolveLegacyRealtimeAudioFormat(); - const tools = normalizeOpenAIRealtimeTools( - cfg.tools, - AZURE_OPENAI_REALTIME_TOOL_NAME_MAX_LENGTH, - ); - return { - type: "session.update", - session: { - modalities: ["text", "audio"], - instructions: cfg.instructions, - voice: cfg.voice ?? "alloy", - input_audio_format: format, - output_audio_format: format, - input_audio_transcription: { - model: "whisper-1", - ...(cfg.language ? { language: cfg.language } : {}), - }, - turn_detection: this.buildTurnDetectionConfig(), - temperature: cfg.temperature ?? 0.8, - ...(tools - ? { - tools, - tool_choice: "auto", - } - : {}), - }, - }; - } - - private buildTurnDetectionConfig(options?: { - createResponse?: boolean; - includeInterruptResponse?: boolean; - }): RealtimeTurnDetectionConfig { - return buildOpenAIRealtimeTurnDetectionConfig({ - autoRespondToAudio: this.config.autoRespondToAudio, - createResponse: options?.createResponse, - includeInterruptResponse: options?.includeInterruptResponse, - interruptResponseOnInputAudio: this.config.interruptResponseOnInputAudio, - prefixPaddingMs: this.config.prefixPaddingMs, - silenceDurationMs: this.config.silenceDurationMs, - vadThreshold: this.config.vadThreshold, - }); - } - - private sendAutoResponseSessionUpdate(createResponse: boolean): void { - const azureDeployment = this.usesAzureDeploymentRealtimeApi(); - const turnDetection = this.buildTurnDetectionConfig({ - createResponse, - includeInterruptResponse: !azureDeployment, - }); - if (azureDeployment) { - this.sendEvent({ type: "session.update", session: { turn_detection: turnDetection } }); - return; - } - this.sendEvent({ - type: "session.update", - session: { type: "realtime", audio: { input: { turn_detection: turnDetection } } }, - }); - } - - private resolveLegacyRealtimeAudioFormat(): "g711_ulaw" | "pcm16" { - return this.audioFormat.encoding === "pcm16" ? "pcm16" : "g711_ulaw"; - } - - private markSessionReady(connection: RealtimeVoiceSessionConnection): void { - if (!this.lifecycle.ready(connection)) { - return; - } - if (this.activeConnectionReason) { - this.config.onEvent?.({ - direction: "server", - type: "session.rotation.ready", - detail: `reason=${this.activeConnectionReason}`, - }); - this.activeConnectionReason = undefined; - } - if (!this.sessionReadyFired) { - this.sessionReadyFired = true; - this.config.onReady?.(); - } - for (const chunk of this.lifecycle.drainPendingAudio()) { - this.sendAudio(chunk); - } - } - - private handleEvent(event: RealtimeEvent, connection: RealtimeVoiceSessionConnection): void { - const emitServerEvent = () => - this.config.onEvent?.({ - direction: "server", - type: event.type, - detail: this.describeServerEvent(event), - ...(event.item_id ? { itemId: event.item_id } : {}), - ...((event.response_id ?? event.response?.id) - ? { responseId: event.response_id ?? event.response?.id } - : {}), - }); - if ( - event.type === "error" && - isOpenAIRealtimeMaxSessionDurationError(readRealtimeErrorDetail(event.error)) - ) { - this.reconnectReason = "max-duration"; - this.activeConnectionReason = "max-duration"; - this.config.onEvent?.({ - direction: "server", - type: "session.rotation", - detail: "reason=max-duration", - }); - this.ws?.close(1000, "max-duration rotation"); - return; - } - if (event.type === "response.done") { - this.handleResponseDone(event, connection, emitServerEvent); - return; - } - if (event.type === "response.cancelled") { - try { - emitServerEvent(); - } finally { - this.releaseResponseState(); - } - return; - } - emitServerEvent(); - switch (event.type) { - case "session.created": - return; - - case "session.updated": { - this.markSessionReady(connection); - return; - } - - case "response.created": - this.responseActive = true; - this.responseCreateInFlight = false; - return; - - case "conversation.output_audio.delta": - case "response.audio.delta": - case "response.output_audio.delta": { - const audioDelta = event.delta ?? event.data; - if (!audioDelta) { - return; - } - const audio = base64ToBuffer(audioDelta); - this.config.onAudio(audio); - if (event.item_id && event.item_id !== this.lastAssistantItemId) { - this.lastAssistantItemId = event.item_id; - this.responseStartTimestamp = this.latestMediaTimestamp; - } else if (this.responseStartTimestamp === null) { - this.responseStartTimestamp = this.latestMediaTimestamp; - } - this.responseActive = true; - this.sendMark(); - return; - } - - case "input_audio_buffer.speech_started": - if (this.config.interruptResponseOnInputAudio ?? this.config.autoRespondToAudio ?? true) { - this.handleBargeIn(); - } - return; - - case "conversation.output_transcript.delta": - case "response.text.delta": - case "response.output_text.delta": - case "response.audio_transcript.delta": - case "response.output_audio_transcript.delta": - if (event.delta) { - this.config.onTranscript?.("assistant", event.delta, false); - } - return; - - case "response.text.done": - case "response.output_text.done": - case "response.audio_transcript.done": - case "response.output_audio_transcript.done": - { - const transcript = event.transcript ?? event.text; - if (transcript) { - this.config.onTranscript?.("assistant", transcript, true); - } - } - return; - - case "conversation.input_transcript.delta": - case "conversation.item.input_audio_transcription.delta": - if (event.delta) { - this.config.onTranscript?.("user", event.delta, false); - } - return; - - case "conversation.item.input_audio_transcription.completed": - if (event.transcript) { - this.config.onTranscript?.("user", event.transcript, true); - } - return; - - case "conversation.item.input_audio_transcription.failed": - this.config.onError?.(new Error(readRealtimeErrorDetail(event.error))); - break; - - case "conversation.item.added": - break; - - case "response.function_call_arguments.delta": - case "response.function_call_arguments.done": - case "conversation.item.done": - // These events are provisional and can also arrive for interrupted, - // incomplete, or cancelled responses. Successful response.done output - // is the sole execution boundary. - return; - - case "error": { - const detail = readRealtimeErrorDetail(event.error); - const rejectedEventId = readRealtimeErrorEventId(event.error); - if (rejectedEventId && rejectedEventId === this.standaloneSpeechEventId) { - this.responseCreateInFlight = false; - this.standaloneSpeechActive = false; - this.standaloneSpeechEventId = null; - this.config.onError?.(new Error(detail)); - if (this.standaloneSpeechQueue.length > 0) { - this.flushStandaloneSpeech(); - } else if (this.responseCreatePending) { - this.flushPendingResponseCreate(); - } - return; - } - const rejectsManualResponseCreate = - this.manualResponseCreateEventId !== null && - readRealtimeErrorEventId(event.error) === this.manualResponseCreateEventId; - if ( - rejectsManualResponseCreate && - detail.startsWith(OPENAI_REALTIME_ACTIVE_RESPONSE_ERROR_PREFIX) - ) { - this.responseActive = true; - this.responseCreateInFlight = false; - this.manualResponseCreateEventId = null; - this.responseCreatePending = true; - return; - } - const rejectsManualResponseCancel = - this.manualResponseCancelEventId !== null && - readRealtimeErrorEventId(event.error) === this.manualResponseCancelEventId; - if (detail === OPENAI_REALTIME_NO_ACTIVE_RESPONSE_CANCEL_ERROR) { - if (!rejectsManualResponseCancel) { - return; - } - this.responseActive = false; - this.responseCancelInFlight = false; - this.manualResponseCancelEventId = null; - if (this.responseCreatePending) { - this.flushPendingResponseCreate(); - } else { - this.restoreAutoRespondAfterManualResponse(); - } - return; - } - if (rejectsManualResponseCreate) { - this.responseCreateInFlight = false; - this.manualResponseCreateEventId = null; - if (this.responseCreatePending) { - this.flushPendingResponseCreate(); - } else { - this.restoreAutoRespondAfterManualResponse(); - } - } - this.config.onError?.(new Error(detail)); - } - - default: - } - } - - private releaseResponseState(options: { drain?: boolean } = {}): void { - this.responseActive = false; - this.responseCreateInFlight = false; - this.manualResponseCreateEventId = null; - this.responseCancelInFlight = false; - this.manualResponseCancelEventId = null; - if (this.standaloneSpeechActive) { - this.standaloneSpeechActive = false; - this.standaloneSpeechEventId = null; - } - if (options.drain === false) { - return; - } - if (this.standaloneSpeechQueue.length > 0) { - this.flushStandaloneSpeech(); - } else if (this.responseCreatePending) { - this.flushPendingResponseCreate(); - } else { - this.restoreAutoRespondAfterManualResponse(); - } - } - - handleBargeIn(options?: RealtimeVoiceBargeInOptions): void { - const assistantItemId = this.lastAssistantItemId; - const responseStartTimestamp = this.responseStartTimestamp; - const force = options?.force === true; - const shouldInterruptProvider = - assistantItemId !== null && - ((responseStartTimestamp !== null && - (this.oldestOutstandingMarkSequence !== null || options?.audioPlaybackActive === true)) || - force); - const audioEndMs = shouldInterruptProvider - ? Math.max( - 0, - responseStartTimestamp === null - ? this.latestMediaTimestamp - : this.latestMediaTimestamp - responseStartTimestamp, - ) - : null; - const minBargeInAudioEndMs = - this.config.minBargeInAudioEndMs ?? OPENAI_REALTIME_DEFAULT_MIN_BARGE_IN_AUDIO_END_MS; - if (!force && audioEndMs !== null && audioEndMs < minBargeInAudioEndMs) { - this.config.onEvent?.({ - direction: "client", - type: "conversation.item.truncate.skipped", - detail: `reason=barge-in audioEndMs=${audioEndMs} minAudioEndMs=${minBargeInAudioEndMs}`, - }); - return; - } - if ( - options?.audioPlaybackActive === true && - this.responseActive && - !this.responseCancelInFlight - ) { - const eventId = `openclaw-response-cancel-${randomUUID()}`; - this.manualResponseCancelEventId = eventId; - this.sendEvent({ type: "response.cancel", event_id: eventId }, "reason=barge-in"); - this.responseCancelInFlight = true; - } - if (shouldInterruptProvider) { - this.sendEvent( - { - type: "conversation.item.truncate", - item_id: assistantItemId, - content_index: 0, - audio_end_ms: audioEndMs, - }, - `reason=barge-in audioEndMs=${audioEndMs}`, - ); - this.config.onClearAudio("barge-in"); - this.clearOutstandingMarks(); - this.lastAssistantItemId = null; - this.responseStartTimestamp = null; - return; - } - this.config.onClearAudio("barge-in"); - } - - private handleCompletedResponse( - event: RealtimeEvent, - connection: RealtimeVoiceSessionConnection, - ): boolean { - if ( - event.type !== "response.done" || - event.response?.status !== "completed" || - !Array.isArray(event.response.output) || - !this.config.onToolCall - ) { - return false; - } - for (const output of event.response.output) { - if (!this.lifecycle.acceptsEvents(connection) || this.ws?.readyState !== WebSocket.OPEN) { - return true; - } - if ( - !isRecord(output) || - output.type !== "function_call" || - (output.status !== undefined && output.status !== "completed") - ) { - continue; - } - const itemId = typeof output.id === "string" ? output.id.trim() || undefined : undefined; - const callId = typeof output.call_id === "string" ? output.call_id.trim() : ""; - const name = typeof output.name === "string" ? output.name.trim() : ""; - if (!callId || !name || this.completedToolCallIds.has(callId)) { - continue; - } - if (this.completedToolCallIds.size >= OpenAIRealtimeVoiceBridge.MAX_COMPLETED_TOOL_CALL_IDS) { - const ws = this.ws; - if (ws) { - this.failConnection( - new Error( - `OpenAI realtime tool-call session limit exceeded (${OpenAIRealtimeVoiceBridge.MAX_COMPLETED_TOOL_CALL_IDS})`, - ), - ws, - connection, - { code: 1008, reason: "Tool-call session limit exceeded" }, - ); - } - return true; - } - this.completedToolCallIds.add(callId); - this.pendingToolCallIds.add(callId); - if (typeof output.arguments !== "string") { - this.rejectToolCallArguments({ - itemId, - callId, - reason: "invalid-json-type", - message: "Invalid tool arguments: expected a JSON object.", - }); - continue; - } - const rawArgs = output.arguments; - if (Buffer.byteLength(rawArgs, "utf8") > OpenAIRealtimeVoiceBridge.MAX_TOOL_ARGUMENT_BYTES) { - this.rejectToolCallArguments({ - itemId, - callId, - reason: "too-large", - message: `Realtime tool arguments exceed the ${OpenAIRealtimeVoiceBridge.MAX_TOOL_ARGUMENT_BYTES}-byte UTF-8 limit`, - }); - continue; - } - let args: unknown; - try { - args = JSON.parse(rawArgs || "{}"); - } catch { - this.rejectToolCallArguments({ - itemId, - callId, - reason: "malformed-json", - message: "Invalid tool arguments: expected a JSON object.", - }); - continue; - } - if (!isRecord(args)) { - this.rejectToolCallArguments({ - itemId, - callId, - reason: "non-object-json", - message: "Invalid tool arguments: expected a JSON object.", - }); - continue; - } - this.config.onToolCall({ itemId: itemId ?? callId, callId, name, args }); - } - return false; - } - - private handleResponseDone( - event: RealtimeEvent, - connection: RealtimeVoiceSessionConnection, - emitServerEvent: () => void, - ): void { - const outcome = normalizeRealtimeVoiceResponseOutcome({ - providerLabel: "OpenAI realtime voice", - response: event.response, - responseId: event.response_id, - }); - let callbackError: unknown; - let providerTerminated = false; - const invoke = (callback: () => void) => { - try { - callback(); - } catch (error) { - callbackError ??= error; - } - }; - try { - invoke(() => this.config.onResponseDone?.(outcome)); - invoke(emitServerEvent); - invoke(() => { - providerTerminated = this.handleCompletedResponse(event, connection); - }); - } finally { - // response.done owns response state regardless of observer success. A fatal tool - // boundary still clears state, but must not start queued work on a closing socket. - const canDrain = - !providerTerminated && - this.lifecycle.acceptsEvents(connection) && - this.ws?.readyState === WebSocket.OPEN; - this.releaseResponseState({ drain: canDrain }); - } - if (callbackError) { - throw callbackError instanceof Error - ? callbackError - : new Error("OpenAI realtime response callback failed", { cause: callbackError }); - } - } - - private rejectToolCallArguments(params: { - itemId?: string; - callId: string; - reason: string; - message: string; - }): void { - this.config.onEvent?.({ - direction: "server", - type: "tool_call.arguments.rejected", - detail: `reason=${params.reason}`, - itemId: params.itemId, - }); - this.submitToolResult(params.callId, { error: params.message }); - } - - private requestResponseCreate(options?: OpenAIRealtimeUserMessageOptions): void { - if ( - this.responseActive || - this.responseCreateInFlight || - this.responseCancelInFlight || - this.continuingToolCallIds.size > 0 || - this.pendingToolCallIds.size > 0 - ) { - this.responseCreatePending = true; - return; - } - this.responseCreatePending = false; - this.responseCreateInFlight = true; - this.suppressAutoRespondForManualResponse(); - const eventId = `openclaw-response-create-${randomUUID()}`; - // Realtime errors can describe unrelated client events. Keep this id until - // the manual turn settles so only its rejection may release VAD suppression. - this.manualResponseCreateEventId = eventId; - this.sendEvent({ - type: "response.create", - event_id: eventId, - ...(options?.toolChoice - ? { response: { output_modalities: ["audio"], tool_choice: options.toolChoice } } - : {}), - }); - } - - private flushStandaloneSpeech(): void { - if ( - this.standaloneSpeechActive || - this.responseActive || - this.responseCreateInFlight || - this.responseCancelInFlight - ) { - return; - } - const text = this.standaloneSpeechQueue.shift(); - if (!text) { - return; - } - const eventId = `openclaw-standalone-speech-${randomUUID()}`; - this.standaloneSpeechActive = true; - this.standaloneSpeechEventId = eventId; - this.responseCreateInFlight = true; - this.sendEvent({ - type: "response.create", - event_id: eventId, - response: { - conversation: "none", - output_modalities: ["audio"], - input: [ - { - type: "message", - role: "user", - content: [{ type: "input_text", text }], - }, - ], - }, - }); - } - - private suppressAutoRespondForManualResponse(): void { - if (this.config.autoRespondToAudio === false || this.autoRespondSuppressedForManualResponse) { - return; - } - // Manual response.create owns this turn. Keep VAD events and interruption active, - // but prevent a second server-owned response until all queued manual work finishes. - this.autoRespondSuppressedForManualResponse = true; - this.sendAutoResponseSessionUpdate(false); - } - - private restoreAutoRespondAfterManualResponse(): void { - if (!this.autoRespondSuppressedForManualResponse) { - return; - } - this.autoRespondSuppressedForManualResponse = false; - this.sendAutoResponseSessionUpdate(true); - } - - private flushPendingResponseCreate(): void { - if (!this.responseCreatePending) { - return; - } - this.responseCreatePending = false; - this.requestResponseCreate(); - } - - private resetRealtimeSessionState(): void { - this.clearOutstandingMarks(); - this.responseStartTimestamp = null; - this.responseActive = false; - this.responseCreateInFlight = false; - this.manualResponseCreateEventId = null; - this.responseCancelInFlight = false; - this.manualResponseCancelEventId = null; - this.responseCreatePending = false; - this.autoRespondSuppressedForManualResponse = false; - this.continuingToolCallIds.clear(); - this.pendingToolCallIds.clear(); - this.lastAssistantItemId = null; - this.completedToolCallIds.clear(); - this.standaloneSpeechQueue = []; - this.standaloneSpeechActive = false; - this.standaloneSpeechEventId = null; - } - - private resetTerminalState(): void { - // Transport retries preserve readiness and rotation attribution. A terminal - // session clears both so explicit bridge reuse starts as a new session. - this.sessionReadyFired = false; - this.reconnectReason = undefined; - this.activeConnectionReason = undefined; - this.resetRealtimeSessionState(); - } - - private failConnection( - error: Error, - ws: WebSocket, - connection: RealtimeVoiceSessionConnection, - close: { code: number; reason: string }, - ): void { - if (this.terminalError) { - return; - } - this.terminalError = error; - this.lifecycle.failure(connection); - this.resetTerminalState(); - try { - this.config.onError?.(error); - } finally { - if (ws.readyState !== WebSocket.CLOSED) { - ws.close(close.code, close.reason); - } else { - this.notifyClose(connection, "error"); - } - } - } - - private notifyClose( - connection: RealtimeVoiceSessionConnection, - outcome: "completed" | "error", - ): void { - const terminalOutcome = this.lifecycle.close(connection, outcome); - if (!terminalOutcome) { - return; - } - this.resetTerminalState(); - this.config.onClose?.(terminalOutcome); - } - - private sendMark(): void { - const sequence = this.nextMarkSequence; - this.nextMarkSequence += 1; - if (this.oldestOutstandingMarkSequence === null) { - this.oldestOutstandingMarkSequence = sequence; - } - this.latestOutstandingMarkSequence = sequence; - const markName = `audio-${sequence}`; - this.config.onMark?.(markName); - } - - private clearOutstandingMarks(): void { - this.oldestOutstandingMarkSequence = null; - this.latestOutstandingMarkSequence = null; - } - - private sendEvent(event: unknown, detail?: string): void { - if (this.ws?.readyState === WebSocket.OPEN) { - const type = - event && typeof event === "object" && typeof (event as { type?: unknown }).type === "string" - ? (event as { type: string }).type - : "unknown"; - this.config.onEvent?.({ direction: "client", type, ...(detail ? { detail } : {}) }); - const payload = JSON.stringify(event); - captureWsEvent({ - url: this.connectionUrl, - direction: "outbound", - kind: "ws-frame", - flowId: this.flowId, - payload, - meta: { - provider: "openai", - capability: "realtime-voice", - }, - }); - this.ws.send(payload); - } - } - - private describeServerEvent(event: RealtimeEvent): string | undefined { - if ( - event.type === "error" || - event.type === "conversation.item.input_audio_transcription.failed" - ) { - return readRealtimeErrorDetail(event.error); - } - if (event.type === "session.created" || event.type === "session.updated") { - const session = isRecord(event.session) ? event.session : undefined; - const tools = Array.isArray(session?.tools) ? session.tools.length : 0; - const rawToolChoice = session?.tool_choice; - const toolChoice = - typeof rawToolChoice === "string" - ? rawToolChoice - : isRecord(rawToolChoice) && typeof rawToolChoice.type === "string" - ? rawToolChoice.type - : "unset"; - return `tools=${tools} toolChoice=${toolChoice}`; - } - if ( - (event.type === "conversation.item.added" || event.type === "conversation.item.done") && - event.item?.type - ) { - return [ - `itemType=${event.item.type}`, - event.item.name ? `name=${event.item.name}` : undefined, - ] - .filter(Boolean) - .join(" "); - } - if (event.type === "response.done") { - const status = event.response?.status; - const details = - event.response?.status_details === undefined - ? undefined - : JSON.stringify(event.response.status_details); - return ( - [status ? `status=${status}` : undefined, details].filter(Boolean).join(" ") || undefined - ); - } - if (event.type === "response.cancelled") { - return "cancelled"; - } - return undefined; - } -} + OPENAI_REALTIME_CAPABILITIES, + OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED, + OPENAI_REALTIME_DEFAULT_MODEL, + OPENAI_REALTIME_INPUT_TRANSCRIPTION_MODEL, + OPENAI_REALTIME_MODELS, + OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED, + OPENAI_REALTIME_VOICES, + buildOpenAIRealtimeGaSessionPolicy, + hasOpenAIChatGptSubscriptionAuthInput, + hasOpenAIRealtimeApiKeyInput, + hasOpenAIRealtimePlatformAuthInput, + normalizeOpenAIRealtimeTools, + normalizeOpenAIRealtimeVoice, + normalizeProviderConfig, + requireOpenAIRealtimePlatformAuth, + resolveOpenAIRealtimePlatformAuth, + resolveOpenAIQuicksilverBridgeAuth, + type OpenAIRealtimeVoice, + type OpenAIRealtimeVoiceProviderConfig, +} from "./realtime-voice-session-policy.js"; function resolveOpenAIRealtimeBrowserOfferHeaders(): Record | undefined { const headers = resolveProviderRequestHeaders({ @@ -2221,7 +211,7 @@ async function createOpenAIRealtimeBrowserSession( gaSideband: { session: sessionConfig, createBridge: ({ apiKey, callId, onTerminal }) => { - const bridge = new OpenAIRealtimeVoiceBridge({ + const bridge = new OpenAIRealtimeBridge({ cfg: req.cfg, providerConfig: req.providerConfig, apiKey, @@ -2268,32 +258,12 @@ async function createOpenAIRealtimeBrowserSession( instructions: buildOpenAIQuicksilverInstructions(req.instructions), ...(req.voice ? {} : configuredVoice ? { voice: configuredVoice } : {}), }; - const subscriptionAuth = await resolveOpenAIChatGptSubscriptionAuth({ - cfg: req.cfg, - agentDir: req.cfg ? resolveAgentDir(req.cfg, req.agentId) : undefined, - }); - if (subscriptionAuth) { - return await quicksilverBroker.createBrowserSession(quicksilverRequest, subscriptionAuth); - } - const auth = await resolveOpenAIRealtimePlatformAuth({ + const auth = await resolveOpenAIQuicksilverBridgeAuth({ configuredApiKey: config.apiKey, cfg: req.cfg, + agentId: req.agentId, }); - if (auth.status === "available") { - return await quicksilverBroker.createBrowserSession(quicksilverRequest, { - type: "api-key", - token: auth.value, - }); - } - if ( - hasOpenAIRealtimePlatformAuthInput({ - configuredApiKey: config.apiKey, - cfg: req.cfg, - }) - ) { - throw new Error(OPENAI_GPT_LIVE_AUTHORED_PLATFORM_AUTH_UNAVAILABLE); - } - throw new Error(OPENAI_GPT_LIVE_AUTH_REQUIRED); + return await quicksilverBroker.createBrowserSession(quicksilverRequest, auth); } const auth = await resolveOpenAIRealtimePlatformAuth({ configuredApiKey: config.apiKey, @@ -2349,14 +319,6 @@ async function createOpenAIRealtimeBrowserSession( }; } -async function cancelOpenAIRealtimeBrowserSession( - quicksilverBroker: OpenAIQuicksilverBrowserSessionBroker | undefined, - _req: OpenAIInternalRealtimeBrowserSessionCreateRequest, - session: RealtimeVoiceBrowserSession, -): Promise { - await quicksilverBroker?.cancelBrowserSession(session); -} - export function buildOpenAIRealtimeVoiceProvider(options?: { quicksilverBrowserSessionBroker?: OpenAIQuicksilverBrowserSessionBroker; logger?: Pick; @@ -2427,7 +389,7 @@ export function buildOpenAIRealtimeVoiceProvider(options?: { }), }); } - return new OpenAIRealtimeVoiceBridge({ + return new OpenAIRealtimeBridge({ ...req, apiKey: config.apiKey, model: config.model, @@ -2530,12 +492,8 @@ export function buildOpenAIRealtimeVoiceProvider(options?: { } return undefined; }, - cancelBrowserSession: (request, session) => - cancelOpenAIRealtimeBrowserSession( - options?.quicksilverBrowserSessionBroker, - request, - session, - ), + cancelBrowserSession: (_request, session) => + options?.quicksilverBrowserSessionBroker?.cancelBrowserSession(session), }; Object.defineProperty(provider, INTERNAL_REALTIME_VOICE_PROVIDER, { configurable: true, @@ -2543,4 +501,3 @@ export function buildOpenAIRealtimeVoiceProvider(options?: { }); return provider; } -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/extensions/openai/realtime-voice-response-control.test.ts b/extensions/openai/realtime-voice-response-control.test.ts new file mode 100644 index 000000000000..3fa31c456aa9 --- /dev/null +++ b/extensions/openai/realtime-voice-response-control.test.ts @@ -0,0 +1,648 @@ +// Openai tests cover realtime voice provider plugin behavior. +import type { RealtimeVoiceBridge } from "openclaw/plugin-sdk/realtime-voice"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const { + FakeWebSocket, + execFileSyncMock, + fetchWithSsrFGuardMock, + isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKeyMock, +} = vi.hoisted(() => { + type Listener = (...args: unknown[]) => void; + + class MockWebSocket { + static readonly OPEN = 1; + static readonly CLOSED = 3; + static instances: MockWebSocket[] = []; + + readonly listeners = new Map(); + readyState = 0; + sent: string[] = []; + closed = false; + terminated = false; + deferClose = false; + deferredClose: (() => void) | undefined; + args: unknown[]; + + constructor(...args: unknown[]) { + this.args = args; + MockWebSocket.instances.push(this); + } + + on(event: string, listener: Listener): this { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + emit(event: string, ...args: unknown[]): void { + for (const listener of this.listeners.get(event) ?? []) { + listener(...args); + } + } + + send(payload: string): void { + this.sent.push(payload); + } + + close(code?: number, reason?: string): void { + this.closed = true; + this.readyState = MockWebSocket.CLOSED; + const emitClose = () => this.emit("close", code ?? 1000, Buffer.from(reason ?? "")); + if (this.deferClose) { + this.deferredClose = emitClose; + return; + } + emitClose(); + } + + terminate(): void { + this.terminated = true; + this.close(1006, "terminated"); + } + + emitDeferredClose(): void { + const emitClose = this.deferredClose; + this.deferredClose = undefined; + emitClose?.(); + } + } + + return { + FakeWebSocket: MockWebSocket, + execFileSyncMock: vi.fn(), + fetchWithSsrFGuardMock: vi.fn(), + isProviderAuthProfileConfiguredMock: vi.fn(), + resolveProviderAuthProfileApiKeyMock: vi.fn(), + }; +}); + +vi.mock("node:child_process", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + execFileSync: execFileSyncMock, + }; +}); + +vi.mock("ws", () => ({ + default: FakeWebSocket, +})); + +vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({ + fetchWithSsrFGuard: fetchWithSsrFGuardMock, +})); + +vi.mock("openclaw/plugin-sdk/provider-auth", () => ({ + isProviderAuthProfileConfigured: isProviderAuthProfileConfiguredMock, + resolveProviderAuthProfileApiKey: resolveProviderAuthProfileApiKeyMock, +})); +import { createOpenAIRealtimeTestSupport } from "./realtime-voice-test-support.js"; + +const { + parseSent, + createNativeBridge, + requireSocket, + beginBridgeConnection, + openSocket, + emitServerEvent, + emitSessionUpdated, + emitCompletedToolCalls, + connectReadyBridge, + expectedResponseCreateEvent, + requireNestedRecord, + expectRecordFields, +} = createOpenAIRealtimeTestSupport({ FakeWebSocket, fetchWithSsrFGuardMock }); + +describe("OpenAI realtime voice response control", () => { + beforeEach(() => { + FakeWebSocket.instances = []; + vi.stubEnv("OPENAI_API_KEY", ""); + execFileSyncMock.mockReset(); + fetchWithSsrFGuardMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReset(); + isProviderAuthProfileConfiguredMock.mockReturnValue(false); + resolveProviderAuthProfileApiKeyMock.mockReset(); + resolveProviderAuthProfileApiKeyMock.mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.useRealTimers(); + vi.unstubAllEnvs(); + }); + + it("suppresses auto responses before draining queued initial greeting audio", async () => { + const bridgeRef: { current?: RealtimeVoiceBridge } = {}; + const onReady = vi.fn(() => { + bridgeRef.current?.triggerGreeting?.("Say exactly: hello from explicit speech."); + }); + const bridge = createNativeBridge({ + instructions: "Be helpful.", + onReady, + }); + bridgeRef.current = bridge; + const { connecting, socket } = beginBridgeConnection(bridge); + + openSocket(socket); + await Promise.resolve(); + + bridge.sendAudio(Buffer.from("before-ready")); + emitSessionUpdated(socket); + await connecting; + + const sent = parseSent(socket); + expect(sent.map((event) => event.type)).toEqual([ + "session.update", + "conversation.item.create", + "session.update", + "response.create", + "input_audio_buffer.append", + ]); + expect(sent[2]).toEqual({ + type: "session.update", + session: { + type: "realtime", + audio: { + input: { + turn_detection: { + type: "server_vad", + threshold: 0.5, + prefix_padding_ms: 300, + silence_duration_ms: 500, + create_response: false, + interrupt_response: true, + }, + }, + }, + }, + }); + expect(sent[4]).toEqual({ + type: "input_audio_buffer.append", + audio: Buffer.from("before-ready").toString("base64"), + }); + expect(sent.filter((event) => event.type === "response.create")).toHaveLength(1); + expect(onReady).toHaveBeenCalledTimes(1); + + emitServerEvent(socket, { type: "response.done" }); + + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); + + it("creates an explicit user item and response for manual speech", async () => { + const onEvent = vi.fn(); + const bridge = createNativeBridge({ onEvent }); + const socket = await connectReadyBridge(bridge); + + bridge.triggerGreeting?.("Say exactly: hello from explicit speech."); + + const sent = parseSent(socket); + expect(sent[1]).toEqual({ + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [ + { + type: "input_text", + text: "Say exactly: hello from explicit speech.", + }, + ], + }, + }); + expectRecordFields( + requireNestedRecord(sent[2]?.session, ["audio", "input", "turn_detection"]), + "manual response turn detection", + { + create_response: false, + interrupt_response: true, + }, + ); + expect(sent[3]).toEqual(expectedResponseCreateEvent()); + expect(JSON.stringify(parseSent(socket).at(-1))).not.toContain("output_modalities"); + expect(onEvent).toHaveBeenCalledWith({ direction: "client", type: "conversation.item.create" }); + expect(onEvent).toHaveBeenCalledWith({ direction: "client", type: "response.create" }); + + emitServerEvent(socket, { type: "response.done" }); + + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); + + it("forces one host-selected function on an otherwise automatic response", async () => { + const bridge = createNativeBridge(); + const socket = await connectReadyBridge(bridge); + + bridge.sendUserMessage?.("Run the deterministic check.", { + toolChoice: { type: "function", name: "lookup_weather" }, + }); + + expect(parseSent(socket).at(-1)).toEqual({ + type: "response.create", + event_id: expect.stringMatching(/^openclaw-response-create-/), + response: { + output_modalities: ["audio"], + tool_choice: { type: "function", name: "lookup_weather" }, + }, + }); + }); + + it("defers manual response.create while a realtime response is active", async () => { + const bridge = createNativeBridge(); + const socket = await connectReadyBridge(bridge); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + + bridge.sendUserMessage?.("queued manual response"); + + expect(parseSent(socket).slice(-1)).toEqual([ + { + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [{ type: "input_text", text: "queued manual response" }], + }, + }, + ]); + + emitServerEvent(socket, { type: "response.done" }); + + expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); + }); + + it("restores automatic audio responses when a manual response is rejected", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const socket = await connectReadyBridge(bridge); + + bridge.triggerGreeting?.("Say exactly: hello from explicit speech."); + + const responseCreateEvent = parseSent(socket).findLast( + (event) => event.type === "response.create", + ); + if (!responseCreateEvent?.event_id) { + throw new Error("expected response.create event id"); + } + + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-2)?.session, ["audio", "input", "turn_detection"]), + "suppressed turn detection", + { + create_response: false, + interrupt_response: true, + }, + ); + + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { + event_id: responseCreateEvent.event_id, + message: "bad response request", + }, + }), + ), + ); + + expect(onError).toHaveBeenCalledWith(new Error("bad response request")); + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); + + it("keeps automatic audio suppressed for unrelated errors during a manual response", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const socket = await connectReadyBridge(bridge); + + bridge.triggerGreeting?.("Say exactly: hello from explicit speech."); + const sessionUpdatesBeforeError = parseSent(socket).filter( + (event) => event.type === "session.update", + ); + + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { event_id: "unrelated-audio-event", message: "bad audio append" }, + }), + ), + ); + + expect(onError).toHaveBeenCalledWith(new Error("bad audio append")); + expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength( + sessionUpdatesBeforeError.length, + ); + + emitServerEvent(socket, { type: "response.done" }); + + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); + + it("flushes a queued manual response after the prior request is rejected", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const socket = await connectReadyBridge(bridge); + + bridge.triggerGreeting?.("Say exactly: first greeting."); + const firstResponseCreate = parseSent(socket).findLast( + (event) => event.type === "response.create", + ); + if (!firstResponseCreate?.event_id) { + throw new Error("expected first response.create event id"); + } + const sessionUpdateCount = parseSent(socket).filter( + (event) => event.type === "session.update", + ).length; + + bridge.sendUserMessage?.("Say exactly: queued follow-up."); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { + event_id: firstResponseCreate.event_id, + message: "bad response request", + }, + }), + ), + ); + + const responseCreates = parseSent(socket).filter((event) => event.type === "response.create"); + expect(responseCreates).toHaveLength(2); + expect(responseCreates[1]).toEqual(expectedResponseCreateEvent()); + expect(responseCreates[1]?.event_id).not.toBe(firstResponseCreate.event_id); + expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength( + sessionUpdateCount, + ); + expect(onError).toHaveBeenCalledWith(new Error("bad response request")); + + emitServerEvent(socket, { type: "response.done" }); + + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); + + it("serializes standalone control speech while an agent tool call is pending", async () => { + const bridge = createNativeBridge({ onToolCall: vi.fn() }); + const socket = await connectReadyBridge(bridge); + emitCompletedToolCalls(socket); + + for (const text of ["status", "steer", "cancel"]) { + bridge.sendUserMessage?.(text); + } + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength(1); + + for (let index = 0; index < 3; index += 1) { + socket.emit( + "message", + Buffer.from( + JSON.stringify({ type: "response.created", response: { id: `resp_control_${index}` } }), + ), + ); + emitServerEvent(socket, { + type: "response.done", + response: { id: `resp_control_${index}`, status: "completed", output: [] }, + }); + expect(parseSent(socket).filter((event) => event.type === "response.create")).toHaveLength( + Math.min(index + 2, 3), + ); + } + }); + + it("drains deferred response.create after response.cancelled", async () => { + const bridge = createNativeBridge(); + const socket = await connectReadyBridge(bridge); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + + bridge.sendUserMessage?.("queued after cancellation"); + socket.emit("message", Buffer.from(JSON.stringify({ type: "response.cancelled" }))); + + expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); + }); + + it("drains deferred response.create after a no-active-response cancellation error", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const socket = await connectReadyBridge(bridge); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + + bridge.sendUserMessage?.("queued after cancellation error"); + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + const responseCancelEvent = parseSent(socket).findLast( + (event) => event.type === "response.cancel", + ); + if (!responseCancelEvent?.event_id) { + throw new Error("expected response.cancel event id"); + } + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { + event_id: responseCancelEvent.event_id, + message: "Cancellation failed: no active response found", + }, + }), + ), + ); + + expect(onError).not.toHaveBeenCalled(); + expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); + }); + + it("ignores a stale cancellation error after a newer manual response starts", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const socket = await connectReadyBridge(bridge); + bridge.setMediaTimestamp(1000); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "response.audio.delta", + item_id: "item_1", + delta: Buffer.from("assistant audio").toString("base64"), + }), + ), + ); + bridge.setMediaTimestamp(1300); + + bridge.handleBargeIn?.({ audioPlaybackActive: true }); + const responseCancelEvent = parseSent(socket).findLast( + (event) => event.type === "response.cancel", + ); + if (!responseCancelEvent?.event_id) { + throw new Error("expected response.cancel event id"); + } + bridge.sendUserMessage?.("queued newer response"); + emitServerEvent(socket, { type: "response.done" }); + const sessionUpdateCount = parseSent(socket).filter( + (event) => event.type === "session.update", + ).length; + + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { + event_id: responseCancelEvent.event_id, + message: "Cancellation failed: no active response found", + }, + }), + ), + ); + + expect(onError).not.toHaveBeenCalled(); + expect(parseSent(socket).filter((event) => event.type === "session.update")).toHaveLength( + sessionUpdateCount, + ); + expect(parseSent(socket).at(-1)).toEqual(expectedResponseCreateEvent()); + + emitServerEvent(socket, { type: "response.done" }); + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); + + it("resets deferred response guards after websocket reconnect", async () => { + vi.useFakeTimers(); + const bridge = createNativeBridge(); + const socket = await connectReadyBridge(bridge); + socket.emit( + "message", + Buffer.from(JSON.stringify({ type: "response.created", response: { id: "resp_1" } })), + ); + bridge.sendUserMessage?.("queued before reconnect"); + + expect(parseSent(socket).slice(-1)[0]?.type).toBe("conversation.item.create"); + + socket.emit("close", 1006, Buffer.from("transient drop")); + await vi.advanceTimersByTimeAsync(1000); + const reconnectedSocket = requireSocket(1); + openSocket(reconnectedSocket); + emitSessionUpdated(reconnectedSocket); + bridge.sendUserMessage?.("Say hello after reconnect."); + + expect(parseSent(reconnectedSocket).slice(-3)).toEqual([ + { + type: "conversation.item.create", + item: { + type: "message", + role: "user", + content: [{ type: "input_text", text: "Say hello after reconnect." }], + }, + }, + expect.objectContaining({ type: "session.update" }), + expectedResponseCreateEvent(), + ]); + }); + + it("turns active-response errors into a deferred response.create retry", async () => { + const onError = vi.fn(); + const bridge = createNativeBridge({ onError }); + const socket = await connectReadyBridge(bridge); + + bridge.sendUserMessage?.("trigger active-response retry"); + const responseCreateEvent = parseSent(socket).findLast( + (event) => event.type === "response.create", + ); + if (!responseCreateEvent?.event_id) { + throw new Error("expected response.create event id"); + } + socket.emit( + "message", + Buffer.from( + JSON.stringify({ + type: "error", + error: { + event_id: responseCreateEvent.event_id, + message: "Conversation already has an active response in progress: resp_1", + }, + }), + ), + ); + const afterError = parseSent(socket); + expect(afterError.filter((event) => event.type === "session.update")).toHaveLength(2); + expectRecordFields( + requireNestedRecord(afterError.at(-2)?.session, ["audio", "input", "turn_detection"]), + "still suppressed turn detection", + { + create_response: false, + interrupt_response: true, + }, + ); + + emitServerEvent(socket, { type: "response.done" }); + + expect(onError).not.toHaveBeenCalled(); + expect(parseSent(socket).slice(-1)).toEqual([expectedResponseCreateEvent()]); + + emitServerEvent(socket, { type: "response.done" }); + + expectRecordFields( + requireNestedRecord(parseSent(socket).at(-1)?.session, ["audio", "input", "turn_detection"]), + "restored turn detection", + { + create_response: true, + interrupt_response: true, + }, + ); + }); +}); diff --git a/extensions/openai/realtime-voice-session-policy.ts b/extensions/openai/realtime-voice-session-policy.ts new file mode 100644 index 000000000000..284de9e583b5 --- /dev/null +++ b/extensions/openai/realtime-voice-session-policy.ts @@ -0,0 +1,643 @@ +import { execFileSync } from "node:child_process"; +import { resolveAgentDir } from "openclaw/plugin-sdk/agent-runtime"; +import { + isProviderAuthProfileConfigured, + resolveProviderAuthProfileApiKey, +} from "openclaw/plugin-sdk/provider-auth"; +import type { + RealtimeVoiceAudioFormat, + RealtimeVoiceBrowserSessionCreateRequest, + RealtimeVoiceBridgeCreateRequest, + RealtimeVoiceProviderCapabilities, + RealtimeVoiceProviderConfig, + RealtimeVoiceTool, +} from "openclaw/plugin-sdk/realtime-voice"; +import { + REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, + REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, +} from "openclaw/plugin-sdk/realtime-voice"; +import { warn } from "openclaw/plugin-sdk/runtime-env"; +import { + normalizeResolvedSecretInputString, + normalizeSecretInputString, +} from "openclaw/plugin-sdk/secret-input"; +import { + asFiniteNumber, + asFiniteNumberInRange, + asSafeIntegerInRange, + normalizeOptionalString, +} from "openclaw/plugin-sdk/string-coerce-runtime"; +import { + readRealtimeErrorDetail, + resolveOpenAIProviderConfigRecord, +} from "./realtime-provider-shared.js"; +import { resolveOpenAIChatGptSubscriptionAuth } from "./realtime-quicksilver-session.js"; +import { OPENAI_GPT_LIVE_MODELS } from "./realtime-quicksilver.js"; + +export type OpenAIRealtimeVoice = + | "alloy" + | "ash" + | "ballad" + | "cedar" + | "coral" + | "echo" + | "marin" + | "sage" + | "shimmer" + | "verse"; + +export type OpenAIRealtimeUserMessageOptions = { + toolChoice?: { type: "function"; name: string }; +}; + +export type OpenAIRealtimeVoiceProviderConfig = { + apiKey?: string; + model?: string; + voice?: OpenAIRealtimeVoice; + temperature?: number; + vadThreshold?: number; + silenceDurationMs?: number; + prefixPaddingMs?: number; + interruptResponseOnInputAudio?: boolean; + minBargeInAudioEndMs?: number; + reasoningEffort?: string; + azureEndpoint?: string; + azureDeployment?: string; + azureApiVersion?: string; +}; + +export type OpenAIRealtimeVoiceBridgeConfig = RealtimeVoiceBridgeCreateRequest & { + apiKey?: string; + callId?: string; + gaSessionPolicy?: RealtimeGaSessionPolicy; + model?: string; + voice?: OpenAIRealtimeVoice; + temperature?: number; + vadThreshold?: number; + silenceDurationMs?: number; + prefixPaddingMs?: number; + interruptResponseOnInputAudio?: boolean; + minBargeInAudioEndMs?: number; + reasoningEffort?: string; + azureEndpoint?: string; + azureDeployment?: string; + azureApiVersion?: string; +}; + +export const OPENAI_REALTIME_DEFAULT_MODEL = "gpt-realtime-2.1"; +// Picker suggestions surfaced through talk.catalog; each value is live-verified +// against the OpenAI realtime APIs. Free-form model values are still accepted. +export const OPENAI_REALTIME_MODELS = [ + "gpt-realtime-2.1", + "gpt-realtime-2.1-mini", + "gpt-realtime-2", + ...OPENAI_GPT_LIVE_MODELS, +] as const; +export const OPENAI_REALTIME_INPUT_TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe"; +export const OPENAI_REALTIME_CAPABILITIES: RealtimeVoiceProviderCapabilities = { + transports: ["webrtc", "gateway-relay"], + inputAudioFormats: [ + REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, + REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, + ], + outputAudioFormats: [ + REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, + REALTIME_VOICE_AUDIO_FORMAT_PCM16_24KHZ, + ], + supportsBrowserSession: true, + supportsBargeIn: true, + handlesInputAudioBargeIn: true, + supportsToolCalls: true, + supportsVideoFrames: true, +}; +export const OPENAI_REALTIME_ACTIVE_RESPONSE_ERROR_PREFIX = + "Conversation already has an active response in progress:"; +export const OPENAI_REALTIME_NO_ACTIVE_RESPONSE_CANCEL_ERROR = + "Cancellation failed: no active response found"; +const OPENAI_REALTIME_MAX_SESSION_DURATION_FRAGMENT = "maximum duration"; +export const OPENAI_VOICE_WS_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024; +export const OPENAI_REALTIME_SIDEBAND_STARTUP_MAX_BYTES = 1024 * 1024; +export const OPENAI_REALTIME_DEFAULT_MIN_BARGE_IN_AUDIO_END_MS = 250; +// Realtime validates this character set but accepts names beyond the 64-character +// cap used by other OpenAI tool surfaces. +const OPENAI_REALTIME_TOOL_NAME_RE = /^[A-Za-z0-9_-]+$/; +export const AZURE_OPENAI_REALTIME_TOOL_NAME_MAX_LENGTH = 64; +export const OPENAI_REALTIME_VOICES = [ + "alloy", + "ash", + "ballad", + "coral", + "echo", + "sage", + "shimmer", + "verse", + "marin", + "cedar", +] as const satisfies readonly OpenAIRealtimeVoice[]; + +export function normalizeOpenAIRealtimeVoice(value: unknown): OpenAIRealtimeVoice | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim().toLowerCase(); + return OPENAI_REALTIME_VOICES.includes(normalized as OpenAIRealtimeVoice) + ? (normalized as OpenAIRealtimeVoice) + : undefined; +} + +export type RealtimeEvent = { + type: string; + delta?: string; + data?: string; + text?: string; + transcript?: string; + item_id?: string; + response_id?: string; + call_id?: string; + name?: string; + arguments?: string; + session?: unknown; + item?: { + id?: string; + type?: string; + name?: string; + call_id?: string; + arguments?: string; + }; + response?: { + id?: string; + status?: string; + status_details?: unknown; + output?: unknown[]; + }; + error?: unknown; +}; + +export type RealtimeTurnDetectionConfig = { + type: "server_vad"; + threshold: number; + prefix_padding_ms: number; + silence_duration_ms: number; + create_response: boolean; + interrupt_response?: boolean; +}; + +type RealtimeGaSessionPolicy = { + type: "realtime"; + model: string; + instructions?: string; + output_modalities: string[]; + audio: { + input: { + format: OpenAIRealtimeAudioFormatConfig; + turn_detection: RealtimeTurnDetectionConfig; + noise_reduction: { type: "near_field" } | null; + transcription: { model: string; language?: string }; + }; + output: { + format: OpenAIRealtimeAudioFormatConfig; + voice: OpenAIRealtimeVoice; + }; + }; + reasoning?: { effort: string }; + tools?: RealtimeVoiceTool[]; + tool_choice?: string; +}; + +export type RealtimeGaSessionUpdate = { + type: "session.update"; + session: RealtimeGaSessionPolicy; +}; + +export type RealtimeAzureDeploymentSessionUpdate = { + type: "session.update"; + session: { + modalities: string[]; + instructions?: string; + voice: OpenAIRealtimeVoice; + input_audio_format: "g711_ulaw" | "pcm16"; + output_audio_format: "g711_ulaw" | "pcm16"; + input_audio_transcription?: { model: string; language?: string }; + turn_detection: RealtimeTurnDetectionConfig; + temperature: number; + tools?: RealtimeVoiceTool[]; + tool_choice?: string; + }; +}; + +type OpenAIRealtimeAudioFormatConfig = + | { + type: "audio/pcm"; + rate: 24000; + } + | { + type: "audio/pcmu"; + }; + +export function normalizeProviderConfig( + config: RealtimeVoiceProviderConfig, +): OpenAIRealtimeVoiceProviderConfig { + const raw = resolveOpenAIProviderConfigRecord(config); + return { + apiKey: normalizeResolvedSecretInputString({ + value: raw?.apiKey, + path: "plugins.entries.voice-call.config.realtime.providers.openai.apiKey", + }), + model: normalizeOptionalString(raw?.model), + voice: normalizeOpenAIRealtimeVoice(raw?.speakerVoice ?? raw?.voice), + temperature: asFiniteNumber(raw?.temperature), + vadThreshold: asUnitInterval(raw?.vadThreshold), + silenceDurationMs: asNonNegativeInteger(raw?.silenceDurationMs), + prefixPaddingMs: asNonNegativeInteger(raw?.prefixPaddingMs), + interruptResponseOnInputAudio: + typeof raw?.interruptResponseOnInputAudio === "boolean" + ? raw.interruptResponseOnInputAudio + : undefined, + minBargeInAudioEndMs: asNonNegativeInteger(raw?.minBargeInAudioEndMs), + reasoningEffort: normalizeOptionalString(raw?.reasoningEffort), + azureEndpoint: normalizeOptionalString(raw?.azureEndpoint), + azureDeployment: normalizeOptionalString(raw?.azureDeployment), + azureApiVersion: normalizeOptionalString(raw?.azureApiVersion), + }; +} + +function asNonNegativeInteger(value: unknown): number | undefined { + return asSafeIntegerInRange(value, { min: 0 }); +} + +function asUnitInterval(value: unknown): number | undefined { + return asFiniteNumberInRange(value, { min: 0, max: 1 }); +} + +type OpenAIRealtimeApiKeyResolution = + | { status: "available"; value: string } + | { status: "missing" }; + +export const OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED = + "OpenAI Realtime voice requires an OpenAI Platform API key"; +const OPENAI_GPT_LIVE_AUTH_REQUIRED = + "GPT-Live Talk requires either an OpenAI Platform API key or a ChatGPT OAuth subscription profile"; +const OPENAI_GPT_LIVE_AUTHORED_PLATFORM_AUTH_UNAVAILABLE = + "GPT-Live Talk requires a working OpenAI Platform API key or ChatGPT OAuth subscription profile. The selected Platform API-key source could not be resolved, so OAuth fallback was not used; fix or remove it."; +export const OPENAI_REALTIME_API_KEY_REQUIRED = "OpenAI Realtime voice requires an API key"; +export const OPENAI_REALTIME_CONFIGURED_API_KEY_REJECTED = + "OpenAI Realtime rejected the selected API key. Update or remove the active OpenAI API-key source"; +const KEYCHAIN_SECRET_REF_RE = /^keychain:([^:]+):([^:]+)$/; +const KEYCHAIN_LOOKUP_TIMEOUT_MS = 5000; +const resolvedKeychainSecretRefCache = new Map(); + +export function isDirectOpenAIRealtimeWebSocketUrl(value: string): boolean { + try { + return new URL(value).hostname === "api.openai.com"; + } catch { + return false; + } +} + +export function isOpenAIRealtimeStartupAuthFailure(error: unknown): boolean { + const record = + typeof error === "object" && error !== null ? (error as Record) : undefined; + const status = record?.status ?? record?.statusCode; + const rawCode = record?.code ?? record?.errorCode; + const code = typeof rawCode === "string" ? rawCode.toLowerCase() : ""; + const message = readRealtimeErrorDetail(error).toLowerCase(); + return ( + status === 401 || + code === "invalid_api_key" || + message.includes("invalid_api_key") || + message.includes("incorrect api key provided") || + message.includes("unexpected server response: 401") + ); +} + +function resolveKeychainSecretRef(value: string): string | undefined { + const trimmed = value.trim(); + const match = KEYCHAIN_SECRET_REF_RE.exec(trimmed); + if (!match) { + return trimmed || undefined; + } + const cached = resolvedKeychainSecretRefCache.get(trimmed); + if (cached) { + return cached; + } + const [, service, account] = match; + if (!service || !account) { + return undefined; + } + try { + const resolved = + execFileSync( + "/usr/bin/security", + ["find-generic-password", "-s", service, "-a", account, "-w"], + { + encoding: "utf8", + stdio: ["ignore", "pipe", "pipe"], + timeout: KEYCHAIN_LOOKUP_TIMEOUT_MS, + }, + ).trim() || undefined; + if (resolved) { + resolvedKeychainSecretRefCache.set(trimmed, resolved); + } + return resolved; + } catch { + return undefined; + } +} + +export function resolveOpenAIRealtimeSecretInput( + configuredApiKey: string | undefined, +): OpenAIRealtimeApiKeyResolution { + const configured = normalizeSecretInputString(configuredApiKey); + if (configured) { + const value = resolveKeychainSecretRef(configured); + return value ? { status: "available", value } : { status: "missing" }; + } + + return { status: "missing" }; +} + +export function resolveOpenAIRealtimeEnvApiKey(): OpenAIRealtimeApiKeyResolution { + const envValue = normalizeSecretInputString(process.env.OPENAI_API_KEY); + if (!envValue) { + return { status: "missing" }; + } + const value = resolveKeychainSecretRef(envValue); + return value ? { status: "available", value } : { status: "missing" }; +} + +function resolveOpenAIRealtimeApiKey( + configuredApiKey: string | undefined, +): OpenAIRealtimeApiKeyResolution { + const configured = resolveOpenAIRealtimeSecretInput(configuredApiKey); + if ( + configured.status === "available" || + hasOpenAIRealtimeConfiguredApiKeyInput(configuredApiKey) + ) { + return configured; + } + return resolveOpenAIRealtimeEnvApiKey(); +} + +export function requireOpenAIRealtimeApiKey( + configuredApiKey: string | undefined, + errorMessage = OPENAI_REALTIME_API_KEY_REQUIRED, +): string { + const resolved = resolveOpenAIRealtimeApiKey(configuredApiKey); + if (resolved.status === "available") { + return resolved.value; + } + throw new Error(errorMessage); +} + +export function hasOpenAIRealtimeConfiguredApiKeyInput( + configuredApiKey: string | undefined, +): boolean { + return Boolean(normalizeSecretInputString(configuredApiKey)); +} + +export function hasOpenAIRealtimeApiKeyInput(configuredApiKey: string | undefined): boolean { + return Boolean( + normalizeSecretInputString(configuredApiKey) ?? + normalizeSecretInputString(process.env.OPENAI_API_KEY), + ); +} + +export function normalizeOpenAIRealtimeTools( + tools: RealtimeVoiceTool[] | undefined, + maxNameLength?: number, +): RealtimeVoiceTool[] | undefined { + const normalized: RealtimeVoiceTool[] = []; + let omitted = 0; + for (const tool of tools ?? []) { + try { + const name = tool.name; + if (typeof name !== "string") { + omitted += 1; + continue; + } + const exceedsLengthLimit = maxNameLength !== undefined && name.length > maxNameLength; + if (exceedsLengthLimit || !OPENAI_REALTIME_TOOL_NAME_RE.test(name)) { + omitted += 1; + continue; + } + normalized.push({ + type: "function", + name, + description: tool.description, + parameters: tool.parameters, + }); + } catch { + omitted += 1; + } + } + if (omitted > 0) { + warn(`openai realtime: omitted ${omitted} tool definition(s) with unsupported names`); + } + return normalized.length > 0 ? normalized : undefined; +} + +function resolveOpenAIRealtimeAudioFormat( + audioFormat: RealtimeVoiceAudioFormat = REALTIME_VOICE_AUDIO_FORMAT_G711_ULAW_8KHZ, +): OpenAIRealtimeAudioFormatConfig { + return audioFormat.encoding === "pcm16" + ? { type: "audio/pcm", rate: 24000 } + : { type: "audio/pcmu" }; +} + +export function buildOpenAIRealtimeTurnDetectionConfig(params: { + autoRespondToAudio?: boolean; + createResponse?: boolean; + includeInterruptResponse?: boolean; + interruptResponseOnInputAudio?: boolean; + prefixPaddingMs?: number; + silenceDurationMs?: number; + vadThreshold?: number; +}): RealtimeTurnDetectionConfig { + const configuredAutoResponse = params.autoRespondToAudio ?? true; + return { + type: "server_vad", + threshold: params.vadThreshold ?? 0.5, + prefix_padding_ms: params.prefixPaddingMs ?? 300, + silence_duration_ms: params.silenceDurationMs ?? 500, + create_response: params.createResponse ?? configuredAutoResponse, + ...(params.includeInterruptResponse + ? { + interrupt_response: params.interruptResponseOnInputAudio ?? configuredAutoResponse, + } + : {}), + }; +} + +export function buildOpenAIRealtimeGaSessionPolicy(params: { + audioFormat?: RealtimeVoiceAudioFormat; + autoRespondToAudio?: boolean; + instructions?: string; + interruptResponseOnInputAudio?: boolean; + language?: string; + model: string; + noiseReduction: { type: "near_field" } | null; + prefixPaddingMs?: number; + reasoningEffort?: string; + silenceDurationMs?: number; + tools?: RealtimeVoiceTool[]; + vadThreshold?: number; + voice: OpenAIRealtimeVoice; +}): RealtimeGaSessionPolicy { + const format = resolveOpenAIRealtimeAudioFormat(params.audioFormat); + return { + type: "realtime", + model: params.model, + ...(params.instructions !== undefined ? { instructions: params.instructions } : {}), + output_modalities: ["audio"], + audio: { + input: { + format, + noise_reduction: params.noiseReduction, + transcription: { + model: OPENAI_REALTIME_INPUT_TRANSCRIPTION_MODEL, + ...(params.language ? { language: params.language } : {}), + }, + turn_detection: buildOpenAIRealtimeTurnDetectionConfig({ + autoRespondToAudio: params.autoRespondToAudio, + includeInterruptResponse: true, + interruptResponseOnInputAudio: params.interruptResponseOnInputAudio, + prefixPaddingMs: params.prefixPaddingMs, + silenceDurationMs: params.silenceDurationMs, + vadThreshold: params.vadThreshold, + }), + }, + output: { + format, + voice: params.voice, + }, + }, + ...(params.reasoningEffort ? { reasoning: { effort: params.reasoningEffort } } : {}), + ...(params.tools ? { tools: params.tools, tool_choice: "auto" } : {}), + }; +} + +export async function resolveOpenAIRealtimePlatformAuth(params: { + configuredApiKey: string | undefined; + cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; +}): Promise { + const configured = resolveOpenAIRealtimeSecretInput(params.configuredApiKey); + if ( + configured.status === "available" || + hasOpenAIRealtimeConfiguredApiKeyInput(params.configuredApiKey) + ) { + return configured; + } + + const profileApiKey = await resolveProviderAuthProfileApiKey({ + provider: "openai", + cfg: params.cfg, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }); + if (profileApiKey) { + return { status: "available", value: profileApiKey }; + } + const envApiKey = resolveOpenAIRealtimeEnvApiKey(); + if (envApiKey.status === "available") { + return envApiKey; + } + return { status: "missing" }; +} + +export async function requireOpenAIRealtimePlatformAuth(params: { + configuredApiKey: string | undefined; + cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; +}): Promise> { + const resolved = await resolveOpenAIRealtimePlatformAuth(params); + if (resolved.status === "available") { + return resolved; + } + throw new Error(OPENAI_REALTIME_PLATFORM_AUTH_REQUIRED); +} + +export async function resolveOpenAIQuicksilverBridgeAuth(params: { + configuredApiKey: string | undefined; + cfg: RealtimeVoiceBridgeCreateRequest["cfg"] | undefined; + agentId?: string; +}) { + const subscriptionAuth = await resolveOpenAIChatGptSubscriptionAuth({ + cfg: params.cfg, + agentDir: + params.cfg && params.agentId ? resolveAgentDir(params.cfg, params.agentId) : undefined, + }); + if (subscriptionAuth) { + return subscriptionAuth; + } + const platformAuth = await resolveOpenAIRealtimePlatformAuth(params); + if (platformAuth.status === "available") { + return { type: "api-key" as const, token: platformAuth.value }; + } + if ( + hasOpenAIRealtimePlatformAuthInput({ + configuredApiKey: params.configuredApiKey, + cfg: params.cfg, + }) + ) { + throw new Error(OPENAI_GPT_LIVE_AUTHORED_PLATFORM_AUTH_UNAVAILABLE); + } + throw new Error(OPENAI_GPT_LIVE_AUTH_REQUIRED); +} + +export function hasOpenAIRealtimePlatformAuthInput(params: { + configuredApiKey: string | undefined; + cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; +}): boolean { + if (hasOpenAIRealtimeConfiguredApiKeyInput(params.configuredApiKey)) { + return true; + } + if ( + isProviderAuthProfileConfigured({ + provider: "openai", + cfg: params.cfg, + profileTypes: ["api_key"], + includeExternalCliAuth: false, + }) + ) { + return true; + } + return hasOpenAIRealtimeApiKeyInput(undefined); +} + +export function hasOpenAIChatGptSubscriptionAuthInput(params: { + cfg: RealtimeVoiceBrowserSessionCreateRequest["cfg"] | undefined; + agentId?: string; +}): boolean { + return isProviderAuthProfileConfigured({ + provider: "openai", + cfg: params.cfg, + agentDir: + params.cfg && params.agentId ? resolveAgentDir(params.cfg, params.agentId) : undefined, + profileTypes: ["oauth"], + includeExternalCliAuth: false, + }); +} + +export function isOpenAIRealtimeMaxSessionDurationError(detail: string): boolean { + const normalized = detail.toLowerCase(); + return ( + normalized.includes("session") && + normalized.includes(OPENAI_REALTIME_MAX_SESSION_DURATION_FRAGMENT) + ); +} + +export function readRealtimeErrorEventId(error: unknown): string | undefined { + if (!error || typeof error !== "object") { + return undefined; + } + const eventId = (error as Record).event_id; + return typeof eventId === "string" ? eventId : undefined; +} + +export function parsePlaybackMarkSequence(markName: string): number | undefined { + const match = /^audio-(\d+)$/u.exec(markName); + if (!match) { + return undefined; + } + const sequence = Number(match[1]); + return Number.isSafeInteger(sequence) && sequence > 0 ? sequence : undefined; +} diff --git a/extensions/openai/realtime-voice-test-support.ts b/extensions/openai/realtime-voice-test-support.ts new file mode 100644 index 000000000000..326445f9ddd4 --- /dev/null +++ b/extensions/openai/realtime-voice-test-support.ts @@ -0,0 +1,318 @@ +import type { + RealtimeVoiceBridge, + RealtimeVoiceBridgeCreateRequest, + RealtimeVoiceTool, +} from "openclaw/plugin-sdk/realtime-voice"; +import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime"; +import { expect, vi } from "vitest"; +import { buildOpenAIRealtimeVoiceProvider } from "./realtime-voice-provider.js"; + +type FakeWebSocketLike = { + sent: string[]; + readyState: number; + emit(event: string, ...args: unknown[]): void; +}; + +type FakeWebSocketConstructor = { + new (...args: unknown[]): T; + readonly OPEN: number; + instances: T[]; +}; + +export function createOpenAIRealtimeTestSupport(deps: { + FakeWebSocket: FakeWebSocketConstructor; + fetchWithSsrFGuardMock: ReturnType; +}) { + const { FakeWebSocket, fetchWithSsrFGuardMock } = deps; + type FakeWebSocketInstance = T; + type SentRealtimeEvent = { + type: string; + event_id?: string; + audio?: string; + item_id?: string; + item?: unknown; + content_index?: number; + audio_end_ms?: number; + session?: { + type?: string; + model?: string; + modalities?: string[]; + instructions?: string; + voice?: string; + input_audio_format?: string; + output_audio_format?: string; + input_audio_transcription?: Record; + turn_detection?: { + create_response?: boolean; + }; + output_modalities?: string[]; + tools?: Array<{ name?: string }>; + audio?: { + input?: { + format?: Record; + noise_reduction?: Record | null; + transcription?: Record; + turn_detection?: { + create_response?: boolean; + interrupt_response?: boolean; + }; + }; + output?: { + format?: Record; + voice?: string; + }; + }; + }; + }; + + function parseSent(socket: FakeWebSocketInstance): SentRealtimeEvent[] { + return socket.sent.map((payload: string) => JSON.parse(payload) as SentRealtimeEvent); + } + + function createNativeBridge( + overrides: Partial = {}, + ): RealtimeVoiceBridge { + return buildOpenAIRealtimeVoiceProvider().createBridge({ + providerConfig: { apiKey: "test-api-key-test" }, + onAudio: vi.fn(), + onClearAudio: vi.fn(), + ...overrides, + }); + } + + function requireSocket(index = 0): FakeWebSocketInstance { + const socket = FakeWebSocket.instances[index]; + if (!socket) { + throw new Error("expected bridge to create a websocket"); + } + return socket; + } + + function beginBridgeConnection( + bridge: RealtimeVoiceBridge, + socketIndex = 0, + ): { connecting: Promise; socket: FakeWebSocketInstance } { + const connecting = bridge.connect(); + return { connecting, socket: requireSocket(socketIndex) }; + } + + function openSocket(socket: FakeWebSocketInstance): void { + socket.readyState = FakeWebSocket.OPEN; + socket.emit("open"); + } + + function emitServerEvent(socket: FakeWebSocketInstance, event: Record): void { + socket.emit("message", Buffer.from(JSON.stringify(event))); + } + + function emitSessionUpdated(socket: FakeWebSocketInstance): void { + emitServerEvent(socket, { type: "session.updated" }); + } + + function emitCompletedToolCalls( + socket: FakeWebSocketInstance, + callIds: string[] = ["call_1"], + ): void { + emitServerEvent(socket, { + type: "response.done", + response: { + id: "response_tools", + status: "completed", + output: callIds.map((callId, index) => ({ + id: `item_${index + 1}`, + type: "function_call", + status: "completed", + call_id: callId, + name: "lookup_weather", + arguments: "{}", + })), + }, + }); + } + + function emitFunctionOutputAdded(socket: FakeWebSocketInstance, callId: string): void { + emitServerEvent(socket, { + type: "conversation.item.added", + item: { type: "function_call_output", call_id: callId }, + }); + } + + function expectedFunctionOutput(callId: string, result: unknown) { + return expect.objectContaining({ + type: "conversation.item.create", + item: { + type: "function_call_output", + call_id: callId, + output: JSON.stringify(result), + }, + }); + } + + async function connectReadyBridge( + bridge: RealtimeVoiceBridge, + socketIndex = 0, + ): Promise { + const { connecting, socket } = beginBridgeConnection(bridge, socketIndex); + openSocket(socket); + emitSessionUpdated(socket); + await connecting; + return socket; + } + + function expectedResponseCreateEvent() { + return expect.objectContaining({ + type: "response.create", + event_id: expect.stringMatching(/^openclaw-response-create-/), + }); + } + + function expectedResponseCancelEvent() { + return expect.objectContaining({ + type: "response.cancel", + event_id: expect.stringMatching(/^openclaw-response-cancel-/), + }); + } + + function createJsonResponse(body: unknown, init?: { status?: number }): Response { + return new Response(JSON.stringify(body), { + status: init?.status ?? 200, + headers: { + "Content-Type": "application/json", + }, + }); + } + + function requireRecord(value: unknown, label: string): Record { + expect(isRecord(value), `${label} must be an object`).toBe(true); + return value as Record; + } + + function requireNestedRecord( + value: unknown, + path: readonly string[], + label = path.join("."), + ): Record { + let current = requireRecord(value, label); + for (const key of path) { + current = requireRecord(current[key], `${label}.${key}`); + } + return current; + } + + function expectRecordFields( + value: unknown, + label: string, + expected: Record, + ): Record { + const record = requireRecord(value, label); + for (const [key, expectedValue] of Object.entries(expected)) { + expect(record[key], `${label}.${key}`).toEqual(expectedValue); + } + return record; + } + + function firstMockCall( + mock: { mock: { calls: Array } }, + label: string, + ): readonly unknown[] { + const call = mock.mock.calls[0]; + if (!call) { + throw new Error(`expected ${label} call`); + } + return call; + } + + function requireFetchRequest(callIndex = 0): Record { + return requireRecord(fetchWithSsrFGuardMock.mock.calls[callIndex]?.[0], "fetch request"); + } + + function requireFetchInit(callIndex = 0): Record { + return requireRecord(requireFetchRequest(callIndex).init, "fetch init"); + } + + function requireFetchHeaders(callIndex = 0): Record { + return requireRecord(requireFetchInit(callIndex).headers, "fetch headers"); + } + + function requireFetchJsonBody(callIndex = 0): Record { + const body = requireFetchInit(callIndex).body; + expect(typeof body, "fetch body must be a JSON string").toBe("string"); + return requireRecord(JSON.parse(body as string), "fetch JSON body"); + } + + function requireSession(socket: FakeWebSocketInstance, index = 0): Record { + return requireRecord(parseSent(socket)[index]?.session, "session"); + } + + function hasSentEventType(socket: FakeWebSocketInstance, type: string): boolean { + return parseSent(socket).some((event) => event.type === type); + } + + function createRealtimeTool(name: string): RealtimeVoiceTool { + return { + type: "function", + name, + description: "Contract test tool", + parameters: { type: "object", properties: {} }, + }; + } + + function createUnreadableToolName(): RealtimeVoiceTool { + return { + type: "function", + get name(): string { + throw new Error("unreadable tool name"); + }, + description: "Contract test tool", + parameters: { type: "object", properties: {} }, + }; + } + + function createMalformedToolName(name: unknown): RealtimeVoiceTool { + return { + type: "function", + name, + description: "Contract test tool", + parameters: { type: "object", properties: {} }, + } as unknown as RealtimeVoiceTool; + } + + function createTestJwt(payload: Record): string { + return [ + Buffer.from(JSON.stringify({ alg: "none" })).toString("base64url"), + Buffer.from(JSON.stringify(payload)).toString("base64url"), + "test-signature", + ].join("."); + } + + return { + parseSent, + createNativeBridge, + requireSocket, + beginBridgeConnection, + openSocket, + emitServerEvent, + emitSessionUpdated, + emitCompletedToolCalls, + emitFunctionOutputAdded, + expectedFunctionOutput, + connectReadyBridge, + expectedResponseCreateEvent, + expectedResponseCancelEvent, + createJsonResponse, + requireRecord, + requireNestedRecord, + expectRecordFields, + firstMockCall, + requireFetchRequest, + requireFetchInit, + requireFetchHeaders, + requireFetchJsonBody, + requireSession, + hasSentEventType, + createRealtimeTool, + createUnreadableToolName, + createMalformedToolName, + createTestJwt, + }; +} From 1c46d517c43b36ba72627577a763a4e90cace12a Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 22:07:35 -0700 Subject: [PATCH 020/165] fix(ui): confirm WhatsApp logout (#122437) Require an account-bound confirmation before deleting WhatsApp credentials, and revalidate Gateway ownership plus account state after the modal resolves. --- .../e2e/channels-whatsapp-logout.e2e.test.ts | 93 ++++++++++++++++++- ui/src/i18n/locales/en.ts | 3 + ui/src/pages/channels/channels-page.ts | 21 ++++- ui/src/pages/channels/whatsapp-logout.ts | 60 ++++++++++++ 4 files changed, 173 insertions(+), 4 deletions(-) create mode 100644 ui/src/pages/channels/whatsapp-logout.ts diff --git a/ui/src/e2e/channels-whatsapp-logout.e2e.test.ts b/ui/src/e2e/channels-whatsapp-logout.e2e.test.ts index 5faa0274ef87..05747ba50946 100644 --- a/ui/src/e2e/channels-whatsapp-logout.e2e.test.ts +++ b/ui/src/e2e/channels-whatsapp-logout.e2e.test.ts @@ -1,6 +1,6 @@ // Control UI tests cover WhatsApp logout feedback against a mocked Gateway. import { expect, it } from "vitest"; -import { installMockGateway } from "../test-helpers/control-ui-e2e.ts"; +import { installMockGateway, waitForConfirmModal } from "../test-helpers/control-ui-e2e.ts"; import { createControlUiE2eSuite } from "./control-ui-e2e-suite.test-support.ts"; const suite = createControlUiE2eSuite({ @@ -13,7 +13,7 @@ const QR_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9WlY9Z8AAAAASUVORK5CYII="; suite.define(() => { - it("keeps the QR visible and explains a no-op logout", async () => { + it("confirms the explicit default account and preserves a no-op logout", async () => { await suite.withPage( { locale: "en-US", @@ -72,6 +72,30 @@ suite.define(() => { await expect(qr.getAttribute("src")).resolves.toBe(QR_DATA_URL); await detail.getByRole("button", { name: "Logout" }).click(); + await expect.poll(async () => gateway.getRequests("channels.logout")).toHaveLength(0); + const firstConfirm = await waitForConfirmModal(page); + await expect(firstConfirm.textContent()).resolves.toContain( + "Log out of WhatsApp account default?", + ); + await expect(firstConfirm.textContent()).resolves.toContain( + "Logging out of account default stops its listener and deletes its saved credentials.", + ); + await firstConfirm.getByRole("button", { name: "Cancel" }).click(); + await expect.poll(() => page.locator("openclaw-modal-dialog").count()).toBe(1); + await expect.poll(async () => gateway.getRequests("channels.logout")).toHaveLength(0); + await expect(qr.getAttribute("src")).resolves.toBe(QR_DATA_URL); + await expect + .poll(() => + detail + .locator("dt", { hasText: "Linked" }) + .locator("xpath=following-sibling::dd[1]") + .textContent(), + ) + .toContain("Yes"); + + await detail.getByRole("button", { name: "Logout" }).click(); + const secondConfirm = await waitForConfirmModal(page); + await secondConfirm.getByRole("button", { name: "Logout" }).click(); await expect .poll(async () => detail.locator(".settings-row__desc").allTextContents()) .toContain( @@ -80,11 +104,76 @@ suite.define(() => { await expect(qr.getAttribute("src")).resolves.toBe(QR_DATA_URL); await expect(detail.getByText("Logged out.", { exact: true }).count()).resolves.toBe(0); await expect.poll(async () => gateway.getRequests("channels.logout")).toHaveLength(1); + expect((await gateway.getRequests("channels.logout"))[0]?.params).toEqual({ + channel: "whatsapp", + accountId: "default", + }); await expect.poll(async () => gateway.getRequests("channels.status")).toHaveLength(3); }, ); }); + it("rejects a captured custom-account logout after the Gateway reconnects", async () => { + await suite.withPage({ locale: "en-US", serviceWorkers: "block" }, async ({ page }) => { + const gateway = await installMockGateway(page, { + methodResponses: { + "channels.status": { + ts: Date.now(), + channelOrder: ["whatsapp"], + channelLabels: { whatsapp: "WhatsApp" }, + channels: { + whatsapp: { + configured: true, + linked: true, + running: true, + connected: true, + reconnectAttempts: 0, + }, + }, + channelAccounts: { + whatsapp: [ + { + accountId: "work", + configured: true, + linked: true, + running: true, + connected: true, + }, + ], + }, + channelDefaultAccountId: { whatsapp: "work" }, + }, + "channels.pairing.list": { + accounts: [], + requests: [], + commandOwnerConfigured: true, + limits: { pendingPerAccount: 3, ttlMs: 3_600_000 }, + }, + "channels.logout": { + channel: "whatsapp", + accountId: "work", + cleared: true, + loggedOut: true, + }, + }, + }); + + await page.goto(`${suite.server.baseUrl}settings/channels`); + await page.locator(".channels-item", { hasText: "WhatsApp" }).first().click(); + const detail = page.locator(".channels-detail"); + await detail.waitFor(); + await detail.getByRole("button", { name: "Logout" }).click(); + const confirm = await waitForConfirmModal(page); + await expect(confirm.textContent()).resolves.toContain("work"); + const socketCount = await gateway.getSocketCount(); + await gateway.closeLatest(1012, "Reconnect during logout confirmation"); + await expect.poll(() => gateway.getSocketCount()).toBeGreaterThan(socketCount); + await confirm.getByRole("button", { name: "Logout" }).click(); + await expect.poll(() => page.locator("openclaw-modal-dialog").count()).toBe(1); + await expect.poll(async () => gateway.getRequests("channels.logout")).toHaveLength(0); + }); + }); + it("preserves standard channel details and the complete Telegram setup wizard", async () => { await suite.withPage({ locale: "en-US", serviceWorkers: "block" }, async ({ page }) => { const channelEntries = [ diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts index 01268476e9ea..a8a8dc9e9f0d 100644 --- a/ui/src/i18n/locales/en.ts +++ b/ui/src/i18n/locales/en.ts @@ -292,6 +292,9 @@ export const en: TranslationMap = { subtitle: "Link WhatsApp Web and monitor connection health.", phoneNumber: "Phone number", loggedOut: "Logged out.", + logoutConfirmTitle: "Log out of WhatsApp account {accountId}?", + logoutConfirmMessage: + "Logging out of account {accountId} stops its listener and deletes its saved credentials.", logoutNotCleared: "No stored WhatsApp session was cleared. It may already be absent, or its auth directory may require manual cleanup.", }, diff --git a/ui/src/pages/channels/channels-page.ts b/ui/src/pages/channels/channels-page.ts index ce5834ab2a13..010861083e92 100644 --- a/ui/src/pages/channels/channels-page.ts +++ b/ui/src/pages/channels/channels-page.ts @@ -27,6 +27,7 @@ import { importNostrProfile, parseValidationErrors, putNostrProfile } from "./no import { createNostrProfileFormState } from "./view.nostr-profile-form.ts"; import { renderChannels } from "./view.ts"; import type { ChannelPairingPrompt } from "./view.types.ts"; +import { runWhatsAppLogoutConfirmation } from "./whatsapp-logout.ts"; import { ChannelWizardHost } from "./wizard-host.ts"; type NostrProfileFormState = ReturnType | null; @@ -283,6 +284,23 @@ class ChannelsPage extends OpenClawLightDomElement { await context.channels.refresh(true); } + private async confirmWhatsAppLogout() { + const context = this.context; + const channels = context.channels; + const scope = this.gateway.capture(); + if (!scope || this.channelsSource !== channels) { + return; + } + await runWhatsAppLogoutConfirmation({ + channels, + getWizardAccountId: () => this.wizardHost.whatsappAccountId, + isCurrent: () => + this.gateway.isCurrent(scope) && + this.context === context && + this.channelsSource === channels, + }); + } + private resolveNostrAccountId(): string { const accounts = this.context?.channels.state.channelsSnapshot?.channelAccounts?.nostr ?? []; return this.nostrProfileAccountId ?? accounts[0]?.accountId ?? "default"; @@ -706,8 +724,7 @@ class ChannelsPage extends OpenClawLightDomElement { void context.channels.startWhatsApp(force, this.wizardHost.whatsappAccountId), onWhatsAppWait: () => void context.channels.waitWhatsApp(this.wizardHost.whatsappAccountId), - onWhatsAppLogout: () => - void context.channels.logoutWhatsApp(this.wizardHost.whatsappAccountId), + onWhatsAppLogout: () => void this.confirmWhatsAppLogout(), onShowAdvancedSettings: (enabled) => this.setShowAdvancedSettings(enabled), onConfigPatch: (path, value) => context.runtimeConfig.patchForm(path, value), onConfigSave: () => void this.saveChannelConfig(), diff --git a/ui/src/pages/channels/whatsapp-logout.ts b/ui/src/pages/channels/whatsapp-logout.ts new file mode 100644 index 000000000000..ec41d236a3c1 --- /dev/null +++ b/ui/src/pages/channels/whatsapp-logout.ts @@ -0,0 +1,60 @@ +// Page-side WhatsApp logout confirmation preserves the selected account and +// Gateway owner across the operator's awaited decision. +import { asNullableRecord } from "@openclaw/normalization-core/record-coerce"; +import type { ApplicationContext } from "../../app/context.ts"; +import { showConfirmDialog } from "../../components/confirm-dialog.ts"; +import { t } from "../../i18n/index.ts"; +import { resolveChannelAccounts } from "../../lib/channels/index.ts"; + +type WhatsAppLogoutParams = { + channels: ApplicationContext["channels"]; + getWizardAccountId: () => string | undefined; + isCurrent: () => boolean; +}; + +function resolveWhatsAppLogoutAccount( + channels: ApplicationContext["channels"], + wizardAccountId: string | undefined, +) { + const snapshot = channels.state.channelsSnapshot; + const accountId = wizardAccountId ?? snapshot?.channelDefaultAccountId.whatsapp ?? "default"; + const account = resolveChannelAccounts(snapshot?.channelAccounts, "whatsapp").find( + (candidate) => candidate.accountId === accountId, + ); + if (!account && wizardAccountId !== undefined) { + return null; + } + return { + accountId, + linked: + account?.linked ?? + (wizardAccountId === undefined + ? asNullableRecord(snapshot?.channels.whatsapp)?.linked + : undefined), + }; +} + +export async function runWhatsAppLogoutConfirmation(params: WhatsAppLogoutParams): Promise { + const account = resolveWhatsAppLogoutAccount(params.channels, params.getWizardAccountId()); + if (!account || !params.isCurrent()) { + return; + } + const confirmed = await showConfirmDialog({ + title: t("channels.whatsapp.logoutConfirmTitle", { accountId: account.accountId }), + message: t("channels.whatsapp.logoutConfirmMessage", { accountId: account.accountId }), + confirmLabel: t("common.logout"), + danger: true, + }); + if (!confirmed || !params.isCurrent()) { + return; + } + const currentAccount = resolveWhatsAppLogoutAccount(params.channels, params.getWizardAccountId()); + if ( + !currentAccount || + currentAccount.accountId !== account.accountId || + currentAccount.linked !== account.linked + ) { + return; + } + await params.channels.logoutWhatsApp(account.accountId); +} From bad4d34982db98be6a51fa4374d70de945ef37bd Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 22:08:42 -0700 Subject: [PATCH 021/165] test(agents): remove aggregate-lane noise from src/agents suites (#122432) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Supervisor-capture tests asserted real telegram/slack channel ids, so their pass/fail depended on which channel plugins the selected vitest lane loads (stubs when focused, real normalizers under unit-fast); switch to a neutral synthetic channel. Two embedded-runner tests carried a shared literal /tmp/openclaw.sqlite storePath — one actually opened it, colliding with stale artifacts across parallel runs; both now use realpath'd auto-cleaned per-test temp dirs. Evidence in PR #122164 body; pre-fix aggregates failed 12/1202 (cli) and 4/4750 (embedded), post-fix green in default and shuffled order. --- .../execute.supervisor-capture.test.ts | 64 ++++++++++--------- .../run.overflow-compaction.test.ts | 11 +++- ...tempt-transcript-lifecycle-prepare.test.ts | 11 +++- 3 files changed, 53 insertions(+), 33 deletions(-) diff --git a/src/agents/cli-runner/execute.supervisor-capture.test.ts b/src/agents/cli-runner/execute.supervisor-capture.test.ts index 47bfee3206c8..6a81f9dcc74f 100644 --- a/src/agents/cli-runner/execute.supervisor-capture.test.ts +++ b/src/agents/cli-runner/execute.supervisor-capture.test.ts @@ -46,6 +46,8 @@ vi.mock("../../gateway/mcp-http.loopback-runtime.js", async (importOriginal) => type ProcessSupervisor = ReturnType; type SupervisorSpawnInput = Parameters[0]; +const TEST_MESSAGE_CHANNEL = "test-channel"; + function recordMcpLoopbackToolCallResult(params: { captureKey: string; toolName: string; @@ -1680,7 +1682,7 @@ describe("executePreparedCliRun supervisor output capture", () => { name: "mcp__openclaw__message", input: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -1702,7 +1704,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -1732,7 +1734,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", text: "done", }), @@ -1752,7 +1754,7 @@ describe("executePreparedCliRun supervisor output capture", () => { name: "mcp__openclaw__message", input: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", text: "done", }, @@ -1792,7 +1794,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", text: "done", }), @@ -1806,7 +1808,7 @@ describe("executePreparedCliRun supervisor output capture", () => { name: "mcp__openclaw__message", input: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: `chat${index}`, message: "done", }, @@ -1856,7 +1858,7 @@ describe("executePreparedCliRun supervisor output capture", () => { name: "mcp__openclaw__message", input: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: `chat${index}`, message: "done", }, @@ -1918,7 +1920,7 @@ describe("executePreparedCliRun supervisor output capture", () => { name: "mcp__openclaw__message", input: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -1965,7 +1967,7 @@ describe("executePreparedCliRun supervisor output capture", () => { name: "mcp__openclaw__message", input: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", dryRun: true, @@ -2011,7 +2013,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -2073,7 +2075,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "edit", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -2103,7 +2105,7 @@ describe("executePreparedCliRun supervisor output capture", () => { it("preserves the current provider for implicit message send targets", async () => { const context = buildPreparedCliRunContext({ output: "text", provider: "google-gemini-cli" }); context.mcpDeliveryCapture = true; - context.params.messageChannel = "slack"; + context.params.messageChannel = TEST_MESSAGE_CHANNEL; context.params.currentChannelId = "C123"; context.params.currentThreadTs = "1700000000.000100"; supervisorSpawnMock.mockImplementationOnce(async (...args: unknown[]) => { @@ -2136,7 +2138,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ - provider: "slack", + provider: TEST_MESSAGE_CHANNEL, to: "C123", }), ]); @@ -2152,7 +2154,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", mediaUrl: "https://example.com/photo.png", @@ -2180,7 +2182,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", text: "done", mediaUrls: ["https://example.com/photo.png"], @@ -2198,7 +2200,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -2224,7 +2226,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", text: "done", }), @@ -2241,7 +2243,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "poll", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", pollQuestion: "Lunch?", pollOption: ["Pizza", "Sushi"], @@ -2268,7 +2270,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", }), ]); @@ -2279,7 +2281,7 @@ describe("executePreparedCliRun supervisor output capture", () => { action: "reply", args: { action: "reply", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, @@ -2288,7 +2290,7 @@ describe("executePreparedCliRun supervisor output capture", () => { action: "sticker", args: { action: "sticker", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", stickerId: "sticker-1", }, @@ -2326,7 +2328,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", }), ]); @@ -2342,7 +2344,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "thread-create", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "new thread", }, @@ -2368,7 +2370,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", }), ]); @@ -2377,7 +2379,7 @@ describe("executePreparedCliRun supervisor output capture", () => { it("records current-target evidence for confirmed implicit reply delivery", async () => { const context = buildPreparedCliRunContext({ output: "text", provider: "google-gemini-cli" }); context.mcpDeliveryCapture = true; - context.params.messageChannel = "telegram"; + context.params.messageChannel = TEST_MESSAGE_CHANNEL; context.params.currentChannelId = "chat123"; supervisorSpawnMock.mockImplementationOnce(async (...spawnArgs: unknown[]) => { const input = spawnArgs[0] as SupervisorSpawnInput; @@ -2410,7 +2412,7 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.messagingToolSentTargets).toEqual([ expect.objectContaining({ tool: "message", - provider: "telegram", + provider: TEST_MESSAGE_CHANNEL, to: "chat123", }), ]); @@ -2508,7 +2510,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "x".repeat(20 * 1024), }, @@ -2532,7 +2534,11 @@ describe("executePreparedCliRun supervisor output capture", () => { expect(result.didSendViaMessagingTool).toBe(true); expect(result.messagingToolSentTargets).toEqual([ - expect.objectContaining({ tool: "message", provider: "telegram", to: "chat123" }), + expect.objectContaining({ + tool: "message", + provider: TEST_MESSAGE_CHANNEL, + to: "chat123", + }), ]); }); @@ -2583,7 +2589,7 @@ describe("executePreparedCliRun supervisor output capture", () => { toolName: "message", args: { action: "send", - channel: "telegram", + channel: TEST_MESSAGE_CHANNEL, target: "chat123", message: "done", }, diff --git a/src/agents/embedded-agent-runner/run.overflow-compaction.test.ts b/src/agents/embedded-agent-runner/run.overflow-compaction.test.ts index 43581fc592cf..94afb30819f3 100644 --- a/src/agents/embedded-agent-runner/run.overflow-compaction.test.ts +++ b/src/agents/embedded-agent-runner/run.overflow-compaction.test.ts @@ -1,4 +1,6 @@ -import { describe, expect, it, vi } from "vitest"; +import path from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { useAutoCleanupTempDirTracker } from "../../../test/helpers/temp-dir.js"; import { OPENCLAW_EMBEDDED_CONTEXT_ENGINE_HOST } from "../../context-engine/host-compat.js"; import { buildContextEngineRuntimeSettings } from "../../context-engine/runtime-settings.js"; import type { ContextEngine } from "../../context-engine/types.js"; @@ -12,6 +14,8 @@ import { createEmbeddedRunContextRecoveryState } from "./run/context-recovery-st import type { PreparedEmbeddedRunInput } from "./run/execution-context.js"; import type { EmbeddedRunAttemptResult } from "./run/types.js"; +const tempDirs = useAutoCleanupTempDirTracker(afterEach); + // Keep this dedicated leaf on the compaction composition boundary. Runtime/auth/lane policy is // covered at its direct owners so this shard never reloads the complete public runner graph. const baseRunParams = { @@ -167,7 +171,10 @@ describe("createEmbeddedRunCompactionRuntime", () => { agentId: "main", sessionId: "session-1", sessionKey: "agent:main:session-1", - storePath: "/tmp/openclaw.sqlite", + storePath: path.join( + tempDirs.make("openclaw-overflow-compaction-session-"), + "openclaw.sqlite", + ), }, adoptSessionId: vi.fn((sessionId?: string) => { if (sessionId) { diff --git a/src/agents/embedded-agent-runner/run/attempt-transcript-lifecycle-prepare.test.ts b/src/agents/embedded-agent-runner/run/attempt-transcript-lifecycle-prepare.test.ts index 8d46654d5423..d233fcb189de 100644 --- a/src/agents/embedded-agent-runner/run/attempt-transcript-lifecycle-prepare.test.ts +++ b/src/agents/embedded-agent-runner/run/attempt-transcript-lifecycle-prepare.test.ts @@ -1,6 +1,10 @@ -import { describe, expect, it, vi } from "vitest"; +import path from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { useAutoCleanupTempDirTracker } from "../../../../test/helpers/temp-dir.js"; import { prepareEmbeddedAttemptTranscriptLifecycle } from "./attempt-transcript-lifecycle-prepare.js"; +const tempDirs = useAutoCleanupTempDirTracker(afterEach); + describe("prepareEmbeddedAttemptTranscriptLifecycle", () => { it("carries the admitted writer fence into nested transcript writes", async () => { const externalAbortController = { @@ -20,7 +24,10 @@ describe("prepareEmbeddedAttemptTranscriptLifecycle", () => { expectedWriterRunId: "run-a", sessionId: "session-a", sessionKey: "agent:main:test", - storePath: "/tmp/openclaw.sqlite", + storePath: path.join( + tempDirs.make("openclaw-attempt-transcript-lifecycle-"), + "openclaw.sqlite", + ), }, }, externalAbortController, From a7e4065dd7a28808fdacde29cd81444bdbe7f757 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 22:08:54 -0700 Subject: [PATCH 022/165] fix: compaction resolves undated model refs (#122422) * fix(agents): unify tiered model resolution for chat and compaction Manual /compact failed with Unknown_model when the agent model was configured as an undated ref (e.g. anthropic/claude-haiku-4-5): the chat run resolved models through a two-tier path (discovery-free lookup, then prepared stores with bundled static-catalog fallback) while both compaction entry points made a single bare resolveModelAsync call and dead-ended before the static catalog could resolve the undated id. resolveTieredModel is now the canonical resolution owner used by the chat run, direct compaction, and queued compaction; the duplicated chat-only tier logic and both bare compaction lookups are removed. Regression test proves chat and manual compaction resolve the same undated configured model through the shared owner. * fix(agents): satisfy lint and test-types on tiered resolution call sites Drop the redundant ?? {} spread fallbacks (spreading undefined is a no-op) and give the test registry mock its real (provider, modelId) signature for check:test-types. --- .../compact.hooks.test.ts | 5 +- .../embedded-agent-runner/compact.queued.ts | 15 +- .../direct-compaction-preparation.ts | 28 +-- .../model-resolution-consistency.test.ts | 214 ++++++++++++++++++ .../embedded-agent-runner/model-resolution.ts | 86 +++++++ .../embedded-agent-runner/run/model-setup.ts | 88 ++----- 6 files changed, 342 insertions(+), 94 deletions(-) create mode 100644 src/agents/embedded-agent-runner/model-resolution-consistency.test.ts create mode 100644 src/agents/embedded-agent-runner/model-resolution.ts diff --git a/src/agents/embedded-agent-runner/compact.hooks.test.ts b/src/agents/embedded-agent-runner/compact.hooks.test.ts index 9dce2cd30198..b2f610a75c60 100644 --- a/src/agents/embedded-agent-runner/compact.hooks.test.ts +++ b/src/agents/embedded-agent-runner/compact.hooks.test.ts @@ -2420,7 +2420,7 @@ describe("compactEmbeddedAgentSession hooks (ownsCompaction engine)", () => { } }); - it("uses the acquired gateway runtime generation for queued model resolution", async () => { + it("uses the acquired gateway runtime generation for queued tiered model resolution", async () => { await compactEmbeddedAgentSession( wrappedCompactionArgs({ allowGatewaySubagentBinding: true, @@ -2434,9 +2434,8 @@ describe("compactEmbeddedAgentSession hooks (ownsCompaction engine)", () => { : undefined; expect(snapshot).toBeDefined(); expect(mockCallArg(resolveModelAsyncMock, 0, 4)).toMatchObject({ - authStorage: {}, - modelRegistry: {}, preparedModelRuntime: snapshot, + skipAgentDiscovery: true, }); }); diff --git a/src/agents/embedded-agent-runner/compact.queued.ts b/src/agents/embedded-agent-runner/compact.queued.ts index 288df555d10c..85be4523eb47 100644 --- a/src/agents/embedded-agent-runner/compact.queued.ts +++ b/src/agents/embedded-agent-runner/compact.queued.ts @@ -56,6 +56,7 @@ import { resolveContextEngineCapabilities } from "./context-engine-capabilities. import { runContextEngineMaintenance } from "./context-engine-maintenance.js"; import { resolveGlobalLane, resolveSessionLane } from "./lanes.js"; import { log } from "./logger.js"; +import { resolveTieredModel } from "./model-resolution.js"; import { resolveModelAsync } from "./model.js"; import type { EmbeddedAgentQueueHandle } from "./run-state.js"; import { @@ -437,7 +438,6 @@ async function compactResolvedContextEngine( let preparedHarnessRuntime = selectedHarnessRuntime; let preparedParams = params; try { - const preparedStores = preparedModelRuntime.createStores(); // Ensure the policy-selected harness plugin so selection can pick implicit codex. await ensureSelectedAgentHarnessPlugin({ config: params.config, @@ -450,15 +450,16 @@ async function compactResolvedContextEngine( workspaceDir: resolvedWorkspaceDir, pluginRegistry: requireActivePluginRegistry(), }); - const { - model: ceModel, - authStorage, - modelRegistry, - } = await resolveModelAsync(ceRuntimeProvider, ceModelId, agentDir, params.config, { + const { resolution: modelResolution } = await resolveTieredModel({ + provider: ceRuntimeProvider, + modelId: ceModelId, + agentDir, + config: params.config, + workspaceDir: resolvedWorkspaceDir, ...initialModelAuth, - ...preparedStores, preparedModelRuntime, }); + const { model: ceModel, authStorage, modelRegistry } = modelResolution; const ceRuntimeModel = ceModel as ProviderRuntimeModel | undefined; // Overrides stay unset when no bound/planned/explicit harness resolved so auth-aware // selection can pick the credential-owning harness (codex for ChatGPT OAuth). diff --git a/src/agents/embedded-agent-runner/direct-compaction-preparation.ts b/src/agents/embedded-agent-runner/direct-compaction-preparation.ts index 442d2c472ee3..44aa89ff9bdf 100644 --- a/src/agents/embedded-agent-runner/direct-compaction-preparation.ts +++ b/src/agents/embedded-agent-runner/direct-compaction-preparation.ts @@ -42,6 +42,7 @@ import { resolveCompactionRuntimeSelection, } from "./compaction-runtime-preparation.js"; import { log } from "./logger.js"; +import { resolveTieredModel } from "./model-resolution.js"; import { resolveModelAsync } from "./model.js"; import type { EmbeddedAgentCompactResult } from "./types.js"; @@ -135,25 +136,26 @@ export async function prepareDirectCompactionAttempt( }; }; const preparedModelRuntime = params.preparedModelRuntime; - const modelResolutionOptions = { - ...preparedModelRuntime.createStores(), - preparedModelRuntime, - workspaceDir: resolvedWorkspace, - }; - const { model, error, authStorage, modelRegistry } = await resolveModelAsync( - runtimeProvider, + const { resolution: modelResolution } = await resolveTieredModel({ + provider: runtimeProvider, modelId, agentDir, - params.config, - { - ...initialModelAuth, - ...modelResolutionOptions, - }, - ); + config: params.config, + workspaceDir: resolvedWorkspace, + ...initialModelAuth, + preparedModelRuntime, + }); + const { model, error, authStorage, modelRegistry } = modelResolution; if (!model) { const reason = error ?? `Unknown model: ${runtimeProvider}/${modelId}`; return { ok: false as const, result: fail(reason) }; } + const modelResolutionOptions = { + authStorage, + modelRegistry, + preparedModelRuntime, + workspaceDir: resolvedWorkspace, + }; // Overrides stay unset when no bound/planned/explicit harness resolved so auth-aware // selection can pick the credential-owning harness (codex for ChatGPT OAuth); native // transcript compaction stays gated on the selected prepared harness. diff --git a/src/agents/embedded-agent-runner/model-resolution-consistency.test.ts b/src/agents/embedded-agent-runner/model-resolution-consistency.test.ts new file mode 100644 index 000000000000..43450f70e011 --- /dev/null +++ b/src/agents/embedded-agent-runner/model-resolution-consistency.test.ts @@ -0,0 +1,214 @@ +import { describe, expect, it, vi } from "vitest"; +import { resolveInitialEmbeddedRunModel } from "./run/runtime-resolution.js"; + +const STATIC_MODEL_ID = "claude-haiku-4-5"; +const PROVIDER = "anthropic"; + +const emptyModelRegistry = { + find: vi.fn((_provider: string, _modelId: string) => null), +}; +const authStorage = { + setRuntimeApiKey: vi.fn(), +}; +const staticCatalogModel = { + provider: PROVIDER, + id: STATIC_MODEL_ID, + name: "Claude Haiku 4.5", + api: "anthropic-messages", + baseUrl: "https://api.anthropic.com", + reasoning: true, + input: ["text", "image"], + contextWindow: 200_000, + maxTokens: 64_000, +}; + +const resolveModelAsyncMock = vi.fn( + async ( + provider: string, + modelId: string, + _agentDir?: string, + _config?: unknown, + options?: { + allowBundledStaticCatalogFallback?: boolean; + authStorage?: unknown; + modelRegistry?: unknown; + }, + ) => { + const stores = { + authStorage: options?.authStorage ?? authStorage, + modelRegistry: options?.modelRegistry ?? emptyModelRegistry, + }; + if (options?.allowBundledStaticCatalogFallback) { + return { ...stores, model: staticCatalogModel }; + } + return { + ...stores, + error: `Unknown model: ${provider}/${modelId}`, + }; + }, +); + +vi.mock("./model.js", () => ({ + createEmptyAgentDiscoveryStores: () => ({ authStorage, modelRegistry: emptyModelRegistry }), + resolveModelAsync: resolveModelAsyncMock, +})); + +vi.mock("../harness/runtime-plugin.js", () => ({ + ensureSelectedAgentHarnessPlugin: vi.fn(async () => undefined), +})); + +vi.mock("../harness/selection.js", () => ({ + selectAgentHarness: vi.fn(() => ({ + id: "openclaw", + label: "OpenClaw", + supports: () => ({ supported: true }), + runAttempt: vi.fn(), + })), +})); + +vi.mock("../openai-routing.js", () => ({ + resolveSelectedOpenAIRuntimeProvider: ({ provider }: { provider: string }) => provider, +})); + +vi.mock("../prepared-model-runtime.js", () => ({ + prepareModelRuntimeSnapshot: vi.fn(), +})); + +vi.mock("./run/setup.js", () => ({ + buildBeforeModelResolveAttachments: vi.fn(() => []), + createNativeModelOwnedRuntimeModel: vi.fn(), + resolveHookModelSelection: vi.fn( + async ({ provider, modelId }: { provider: string; modelId: string }) => ({ + provider, + modelId, + }), + ), + resolveNativeModelOwnedHarnessId: vi.fn(() => undefined), +})); + +vi.mock("./compaction-runtime-preparation.js", () => ({ + resolveCompactionRuntimeSelection: ({ + provider, + modelId, + }: { + provider: string; + modelId: string; + }) => ({ + runtimePolicySessionKey: "agent:main:test", + runtimePolicyAgentId: "main", + boundHarnessRuntime: undefined, + selectedHarnessRuntimeOverride: undefined, + runtimeModelAuth: { plan: undefined, authProfileId: undefined, modelAuth: undefined }, + provider, + runtimeProvider: provider, + contextConfigProvider: provider, + modelId, + }), + prepareCompactionHarnessAuth: vi.fn(async () => ({ + runtimeAuthProfileStore: {}, + runtimeAuthPreparation: { + plan: { selectedAuthMode: "api-key" }, + attempts: [{ kind: "direct", plan: { selectedAuthMode: "api-key" } }], + }, + selectedPreparedHarness: { id: "openclaw" }, + providerUsesProfileScopedModelMetadata: false, + })), +})); + +vi.mock("../runtime-plan/resolve-auth.js", () => ({ + resolvePreparedRuntimeAuthAttempts: vi.fn(async ({ model, attempts }) => ({ + model, + auth: { apiKey: "test-api-key", mode: "api_key", source: "test" }, + plan: attempts[0].plan, + })), + resolvePreparedRuntimeModelAuth: vi.fn(), +})); + +vi.mock("../../plugins/provider-runtime.js", () => ({ + prepareProviderRuntimeAuth: vi.fn(async () => undefined), +})); + +vi.mock("../provider-secret-egress.js", () => ({ + protectPreparedProviderRuntimeAuth: (value: unknown) => value, + unwrapSecretSentinelsForProviderEgress: (value: unknown) => value, +})); + +vi.mock("../provider-request-config.js", () => ({ + applyPreparedRuntimeAuthToModel: (model: unknown) => model, +})); + +vi.mock("../sandbox.js", () => ({ + resolveSandboxContext: vi.fn(async () => undefined), +})); + +vi.mock("./compaction-runtime-context.js", () => ({ + resolveEmbeddedCompactionThinkingLevel: vi.fn(() => "off"), +})); + +vi.mock("./logger.js", () => ({ + log: { warn: vi.fn() }, +})); + +const { resolveEmbeddedRunModelSetup } = await import("./run/model-setup.js"); +const { prepareDirectCompactionAttempt } = await import("./direct-compaction-preparation.js"); + +describe("embedded model resolution consistency", () => { + it("resolves the same undated configured model for chat and manual compaction", async () => { + const config = { + agents: { + defaults: { + model: { primary: `${PROVIDER}/${STATIC_MODEL_ID}` }, + }, + }, + }; + const target = resolveInitialEmbeddedRunModel({ config }); + const preparedModelRuntime = { + agentDir: "/tmp/agents/main/agent", + config, + workspaceDir: "/tmp/openclaw-model-resolution", + pluginRegistry: {}, + configuredRuntimeModels: [], + inlineProviderModels: [], + createStores: () => ({ authStorage, modelRegistry: emptyModelRegistry }), + }; + + const chat = await resolveEmbeddedRunModelSetup({ + runParams: { + config, + prompt: "hello", + sessionId: "chat-session", + agentId: "main", + } as never, + ...target, + agentDir: preparedModelRuntime.agentDir, + workspaceDir: preparedModelRuntime.workspaceDir, + globalLane: "test", + hookRunner: undefined, + hookContext: {} as never, + onHooksResolved: vi.fn(), + preparedModelRuntime: preparedModelRuntime as never, + }); + expect(chat.model).toMatchObject({ provider: PROVIDER, id: STATIC_MODEL_ID }); + + const compaction = await prepareDirectCompactionAttempt({ + config, + provider: target.provider, + model: target.modelId, + agentId: "main", + sessionId: "compact-session", + sessionKey: "agent:main:compact-session", + sessionFile: "agent:main:compact-session", + workspaceDir: preparedModelRuntime.workspaceDir, + preparedModelRuntime: preparedModelRuntime as never, + }); + + expect(emptyModelRegistry.find(PROVIDER, STATIC_MODEL_ID)).toBeNull(); + if (!compaction.ok) { + throw new Error(`manual compaction failed: ${compaction.result.reason}`); + } + expect(compaction.value.runtimeModel).toMatchObject({ + provider: PROVIDER, + id: STATIC_MODEL_ID, + }); + }); +}); diff --git a/src/agents/embedded-agent-runner/model-resolution.ts b/src/agents/embedded-agent-runner/model-resolution.ts new file mode 100644 index 000000000000..9a2f38d69eaf --- /dev/null +++ b/src/agents/embedded-agent-runner/model-resolution.ts @@ -0,0 +1,86 @@ +import type { OpenClawConfig } from "../../config/types.openclaw.js"; +import { resolveDefaultAgentDir } from "../agent-scope.js"; +import type { AuthProfileCredential } from "../auth-profiles/types.js"; +import { + prepareModelRuntimeSnapshot, + type PreparedModelRuntimeSnapshot, +} from "../prepared-model-runtime.js"; +import { resolveModelAsync } from "./model.js"; + +type ModelResolution = Awaited>; + +/** Resolves embedded-run models through discovery first, then the prepared static catalog. */ +export async function resolveTieredModel(params: { + provider: string; + fallbackProvider?: string; + modelId: string; + agentDir: string; + config?: OpenClawConfig; + workspaceDir: string; + authProfileId?: string; + authProfileMode?: AuthProfileCredential["type"] | "aws-sdk"; + preparedModelRuntime?: PreparedModelRuntimeSnapshot; + staticCatalogOwnsTransport?: boolean; +}): Promise<{ provider: string; resolution: ModelResolution }> { + const providers = + params.fallbackProvider && params.fallbackProvider !== params.provider + ? [params.provider, params.fallbackProvider] + : [params.provider]; + let firstResolution: ModelResolution | undefined; + const resolveCandidates = async (options: Parameters[4]) => { + for (const provider of providers) { + const resolution = await resolveModelAsync( + provider, + params.modelId, + params.agentDir, + params.config, + options, + ); + firstResolution ??= resolution; + if (resolution.model) { + return { provider, resolution }; + } + } + return undefined; + }; + const firstTier = await resolveCandidates({ + skipAgentDiscovery: true, + allowBundledStaticCatalogFallback: params.staticCatalogOwnsTransport, + preferBundledStaticCatalogTransport: params.staticCatalogOwnsTransport, + preparedModelRuntime: params.preparedModelRuntime, + workspaceDir: params.workspaceDir, + authProfileId: params.authProfileId, + authProfileMode: params.authProfileMode, + }); + if (firstTier) { + return firstTier; + } + if (params.staticCatalogOwnsTransport) { + return { + provider: params.fallbackProvider ?? params.provider, + resolution: firstResolution!, + }; + } + const config = params.config ?? {}; + const preparedModelRuntime = + params.preparedModelRuntime ?? + (await prepareModelRuntimeSnapshot({ + config, + agentDir: params.agentDir, + inheritedAuthDir: resolveDefaultAgentDir(config), + workspaceDir: params.workspaceDir, + })); + return ( + (await resolveCandidates({ + ...preparedModelRuntime.createStores(), + workspaceDir: params.workspaceDir, + authProfileId: params.authProfileId, + authProfileMode: params.authProfileMode, + allowBundledStaticCatalogFallback: true, + preparedModelRuntime, + })) ?? { + provider: params.fallbackProvider ?? params.provider, + resolution: firstResolution!, + } + ); +} diff --git a/src/agents/embedded-agent-runner/run/model-setup.ts b/src/agents/embedded-agent-runner/run/model-setup.ts index a3c1330b3c3b..4a484f350a21 100644 --- a/src/agents/embedded-agent-runner/run/model-setup.ts +++ b/src/agents/embedded-agent-runner/run/model-setup.ts @@ -1,14 +1,11 @@ import { requireActivePluginRegistry } from "../../../plugins/runtime.js"; -import { resolveDefaultAgentDir } from "../../agent-scope.js"; import { FailoverError } from "../../failover-error.js"; import { ensureSelectedAgentHarnessPlugin } from "../../harness/runtime-plugin.js"; import { selectAgentHarness } from "../../harness/selection.js"; import { resolveSelectedOpenAIRuntimeProvider } from "../../openai-routing.js"; -import { - prepareModelRuntimeSnapshot, - type PreparedModelRuntimeSnapshot, -} from "../../prepared-model-runtime.js"; -import { createEmptyAgentDiscoveryStores, resolveModelAsync } from "../model.js"; +import type { PreparedModelRuntimeSnapshot } from "../../prepared-model-runtime.js"; +import { resolveTieredModel } from "../model-resolution.js"; +import { createEmptyAgentDiscoveryStores } from "../model.js"; import type { RunEmbeddedAgentParams } from "./params.js"; import { resolveRequestStreamTransportOverrides } from "./runtime-resolution.js"; import { @@ -99,8 +96,7 @@ export async function resolveEmbeddedRunModelSetup(params: { const nativeModelOwned = nativeModelOwnedHarnessId !== undefined; const modelConfigProvider = provider; let resolvedModelProvider = provider; - let firstModelResolution: Awaited> | undefined; - let modelResolution: Awaited> | undefined; + let modelResolution; if (nativeModelOwned) { modelResolution = { model: createNativeModelOwnedRuntimeModel({ provider, modelId }), @@ -116,69 +112,19 @@ export async function resolveEmbeddedRunModelSetup(params: { config: runParams.config, workspaceDir: params.workspaceDir, }); - const modelResolutionProviders = - selectedRuntimeProvider !== provider ? [selectedRuntimeProvider, provider] : [provider]; - for (const candidateProvider of modelResolutionProviders) { - const candidateResolution = await resolveModelAsync( - candidateProvider, - modelId, - params.agentDir, - runParams.config, - { - // Dynamic hooks can resolve an explicit model without generating models.json first. - skipAgentDiscovery: true, - allowBundledStaticCatalogFallback: pluginHarnessOwnsTransport, - preferBundledStaticCatalogTransport: pluginHarnessOwnsTransport, - preparedModelRuntime: params.preparedModelRuntime, - workspaceDir: params.workspaceDir, - authProfileId: runParams.authProfileId, - }, - ); - firstModelResolution ??= candidateResolution; - if (candidateResolution.model) { - resolvedModelProvider = candidateProvider; - modelResolution = candidateResolution; - break; - } - } - if (!modelResolution && pluginHarnessOwnsTransport) { - modelResolution = firstModelResolution; - } - if (!modelResolution) { - const config = runParams.config ?? {}; - const preparedModelRuntime = - params.preparedModelRuntime ?? - (await prepareModelRuntimeSnapshot({ - config, - agentDir: params.agentDir, - inheritedAuthDir: resolveDefaultAgentDir(config), - workspaceDir: params.workspaceDir, - })); - const preparedStores = preparedModelRuntime.createStores(); - for (const candidateProvider of modelResolutionProviders) { - const candidateResolution = await resolveModelAsync( - candidateProvider, - modelId, - params.agentDir, - runParams.config, - { - authStorage: preparedStores.authStorage, - modelRegistry: preparedStores.modelRegistry, - workspaceDir: params.workspaceDir, - authProfileId: runParams.authProfileId, - allowBundledStaticCatalogFallback: true, - preparedModelRuntime, - }, - ); - firstModelResolution ??= candidateResolution; - if (candidateResolution.model) { - resolvedModelProvider = candidateProvider; - modelResolution = candidateResolution; - break; - } - } - } - modelResolution ??= firstModelResolution; + const tieredResolution = await resolveTieredModel({ + provider: selectedRuntimeProvider, + ...(selectedRuntimeProvider !== provider ? { fallbackProvider: provider } : {}), + modelId, + agentDir: params.agentDir, + config: runParams.config, + workspaceDir: params.workspaceDir, + authProfileId: runParams.authProfileId, + preparedModelRuntime: params.preparedModelRuntime, + staticCatalogOwnsTransport: pluginHarnessOwnsTransport, + }); + resolvedModelProvider = tieredResolution.provider; + modelResolution = tieredResolution.resolution; } if (!modelResolution) { throw new FailoverError(`Unknown model: ${provider}/${modelId}`, { From 00fc1bd123820eb759bfe65ba778c37c1f4c0f9f Mon Sep 17 00:00:00 2001 From: Sarah Fortune Date: Tue, 11 Aug 2026 22:09:46 -0700 Subject: [PATCH 023/165] fix(slack): scope enterprise channel and user policies by workspace (#122346) * fix(slack): scope channel policies by workspace * fix(slack): scope user policies by workspace * fix(slack): preserve workspace policies at ingress * test(slack): use canonical workspace ids * chore(slack): remove stale allowlist import * fix(slack): require workspace-scoped grid policies * test(slack): scope enterprise policy fixtures * style(slack): format workspace policy changes * fix(slack): preserve workspace policy wildcards * fix(slack): retain workspace system-event policies * fix(slack): scope bot policy identities * fix(slack): retain workspace in group policy * fix(slack): preserve workspace DM allowlists --------- Co-authored-by: Sarah Fortune --- docs/channels/slack.md | 33 +++-- docs/gateway/config-channels.md | 8 +- extensions/slack/src/action-runtime.ts | 19 ++- extensions/slack/src/doctor.test.ts | 18 ++- extensions/slack/src/doctor.ts | 20 ++- extensions/slack/src/group-policy.test.ts | 89 ++++++++++++++ extensions/slack/src/group-policy.ts | 22 +++- .../slack/src/monitor/allow-list.test.ts | 61 ++++++++++ extensions/slack/src/monitor/allow-list.ts | 66 +++++++++- extensions/slack/src/monitor/auth.test.ts | 69 ++++++++++- extensions/slack/src/monitor/auth.ts | 114 +++++++++++++----- .../slack/src/monitor/channel-config.ts | 19 ++- extensions/slack/src/monitor/context.test.ts | 42 +++++++ extensions/slack/src/monitor/context.ts | 11 +- extensions/slack/src/monitor/dm-auth.test.ts | 25 ++++ extensions/slack/src/monitor/dm-auth.ts | 2 + .../src/monitor/enterprise-install.test.ts | 35 +++++- .../slack/src/monitor/enterprise-install.ts | 30 +++-- .../slack/src/monitor/events/channels.ts | 1 + .../events/interactions.block-actions.ts | 3 + .../slack/src/monitor/events/reactions.ts | 4 + .../monitor/message-handler/prepare.test.ts | 52 ++++++++ .../src/monitor/message-handler/prepare.ts | 6 +- extensions/slack/src/monitor/monitor.test.ts | 87 +++++++++++++ extensions/slack/src/monitor/slash.ts | 4 + extensions/slack/src/resolve-channels.test.ts | 15 +++ extensions/slack/src/resolve-channels.ts | 39 +++++- extensions/slack/src/resolve-users.test.ts | 15 +++ extensions/slack/src/resolve-users.ts | 31 ++++- extensions/slack/src/security-doctor.ts | 17 ++- extensions/slack/src/target-parsing.ts | 6 +- extensions/slack/src/targets.test.ts | 10 ++ 32 files changed, 881 insertions(+), 92 deletions(-) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 2b4d0d5ce92e..41cee93e5d7b 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -268,13 +268,17 @@ the enterprise account with the same Request URL path: allowFrom: ["*"], groupPolicy: "allowlist", channels: { - C0123456789: { requireMention: true }, + "team:T0123456789:channel:C0123456789": { requireMention: true }, }, }, }, } ``` +For each selected workspace, open it in Slack's web app and copy the `T...` +workspace ID from `https://app.slack.com/client/T.../...`. Use that workspace ID +with the channel's `C...` ID in every qualified policy key, as shown above. + At startup, OpenClaw uses Slack `auth.test` to detect whether the token belongs to a workspace installation or an Enterprise Grid org-wide installation. No installation-mode setting is required. Slack remains the source of truth for @@ -324,14 +328,18 @@ validated listener-owned client remains in the active event turn. The in-memory send queue and thread-participation records are partitioned by that event's workspace; the client itself is never serialized or persisted. -Channel policy keys accept raw stable Slack channel IDs, `channel:`, or the -`"*"` wildcard. `dm.groupChannels` accepts raw stable channel IDs or -`channel:`, but not `"*"`. OpenClaw normalizes the ID forms to the raw -channel ID for runtime matching; the channel prefixes `slack:`, `group:`, and -`mpim:` fail startup. +Enterprise channel policy keys must use +`team::channel:` or the `"*"` wildcard. +`dm.groupChannels` requires the workspace-qualified form and does not accept +`"*"`. A delivered Enterprise event never falls back from its qualified +workspace and channel identity to a bare channel ID. Workspace installations +retain raw stable channel IDs and `channel:` compatibility. The channel +prefixes `slack:`, `group:`, and `mpim:` fail startup. -User policy entries in `allowFrom`, `reactionAllowlist`, and per-channel `users` -accept raw stable Slack user IDs, `slack:`, `user:`, or `"*"`. +Enterprise user policy entries in `allowFrom`, `reactionAllowlist`, and +per-channel `users` must use `team::user:` or `"*"`. A +workspace-scoped sender never matches a bare user ID. Workspace installations +retain raw stable user IDs, `slack:`, and `user:` compatibility. Enterprise `toolsBySender` keys accept raw stable user IDs, `id:`, `channel:slack:`, or `"*"`. Names, slugs, display names, and email addresses fail startup. IDs must use Slack's canonical uppercase prefix and body @@ -351,8 +359,9 @@ rejected before authorization or system-event handling. Enterprise DMs support the same `disabled`, `open`, `allowlist`, and `pairing` policies as workspace installs. Pairing approvals are stored as `team::user:` and are applied only to events from that -workspace. Explicit account `allowFrom` entries remain organization-wide; -channel and sender policy continues to apply to channel messages. +workspace. Explicit account `allowFrom` entries use the same qualified form and +apply only to that workspace; channel and sender policy continues to apply to +channel messages. ## Install @@ -1303,7 +1312,7 @@ Current Slack message actions include `send`, `upload-file`, `download-file`, `r - `allowlist` - `disabled` - Channel allowlist lives under `channels.slack.channels` and **must use stable Slack channel IDs** (for example `C12345678`) as config keys. + Channel allowlist lives under `channels.slack.channels` and **must use stable Slack channel IDs** (for example `C12345678`) as config keys. Enterprise Grid org installs require `team::channel:` so policies cannot cross workspace boundaries. Runtime note: if `channels.slack` is completely missing (env-only setup), runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set). @@ -1936,7 +1945,7 @@ Primary reference: [Configuration reference - Slack](/gateway/config-channels#sl Check, in order: - `groupPolicy` - - channel allowlist (`channels.slack.channels`) — **keys must be channel IDs** (`C12345678`), not names (`#channel-name`). Name-based keys silently fail under `groupPolicy: "allowlist"` because channel routing is ID-first by default. To find an ID: right-click the channel in Slack → **Copy link** — the `C...` value at the end of the URL is the channel ID. + - channel allowlist (`channels.slack.channels`) — **keys must be channel IDs** (`C12345678`) or workspace-qualified channel targets (`team::channel:`), not names (`#channel-name`). Name-based keys silently fail under `groupPolicy: "allowlist"` because channel routing is ID-first by default. To find an ID: right-click the channel in Slack → **Copy link** — the `C...` value at the end of the URL is the channel ID. - `requireMention` - per-channel `users` allowlist - `messages.groupChat.visibleReplies`: normal group/channel requests default to `"automatic"`. If you opted into `"message_tool"` and logs show assistant text with no `message(action=send)` call, the model missed the visible message-tool path. Final text stays private in this mode; inspect the gateway verbose log for suppressed payload metadata, or set it to `"automatic"` if you want every normal assistant final reply posted through the legacy path. diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md index 87234c2fc71f..c4b074c9d5e8 100644 --- a/docs/gateway/config-channels.md +++ b/docs/gateway/config-channels.md @@ -468,9 +468,11 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat - Slack detects Enterprise Grid org-wide installations automatically from the bot token with `auth.test`; no installation-mode setting is required. Enterprise DMs support `disabled`, `open`, `allowlist`, and workspace-scoped - `pairing`. Channel and user policies must use stable Slack IDs; mutable names - and unsupported channel prefixes fail startup. Mention-pattern channel - scopes and static route-binding peers use workspace-qualified Slack targets. + `pairing`. Channel and user policies must use + `team::channel:` or `team::user:`; + bare IDs, mutable names, and unsupported channel prefixes fail startup. + Mention-pattern channel scopes and static route-binding peers use + workspace-qualified Slack targets. Direct Socket Mode or HTTP messages, mentions, workspace-qualified actions, deferred delivery, proactive sends, supported event listeners and interactions, static route bindings, and Slack-native approvals from diff --git a/extensions/slack/src/action-runtime.ts b/extensions/slack/src/action-runtime.ts index 387cee5112f5..e6cb787549df 100644 --- a/extensions/slack/src/action-runtime.ts +++ b/extensions/slack/src/action-runtime.ts @@ -11,6 +11,8 @@ import type { ResolvedSlackAccount } from "./accounts.js"; import { parseSlackBlocksInput } from "./blocks-input.js"; import type { SlackConversationInfo } from "./channel-type.js"; import { assertSlackDetachedTargetAllowed } from "./detached-target-admission.js"; +import { buildSlackChannelIdCandidates } from "./group-policy.js"; +import { getSlackInstallationKind } from "./installation-identity-state.js"; import { SLACK_TEXT_LIMIT } from "./limits.js"; import { resolveSlackChannelConfig } from "./monitor/channel-config.js"; import { isSlackChannelAllowedByPolicy } from "./monitor/policy.js"; @@ -282,6 +284,7 @@ function resolveSlackChannelReadPolicy(params: { account: ResolvedSlackAccount; cfg: OpenClawConfig; channelId: string; + teamId?: string; channelName?: string; conversationReadOrigin?: ConversationReadInvocationOrigin; metadataResolved?: boolean; @@ -290,6 +293,8 @@ function resolveSlackChannelReadPolicy(params: { const channels = params.account.config.channels; const channelKeys = Object.keys(channels ?? {}); const channelConfig = resolveSlackChannelConfig({ + teamId: params.teamId, + allowUnscoped: getSlackInstallationKind(params.account.accountId) !== "enterprise", channelId: params.channelId, channelName: params.channelName, channels, @@ -344,7 +349,7 @@ function resolveSlackChannelReadPolicy(params: { params.account.config.dm?.enabled !== false && params.account.config.dm?.groupEnabled === true && (params.currentConversation || - isSlackGroupDmTargetConfigured(params.account, params.channelId)), + isSlackGroupDmTargetConfigured(params.account, params.channelId, params.teamId)), shouldResolveName, }; } @@ -461,16 +466,26 @@ async function assertSlackReadTargetAllowed(params: { } } -function isSlackGroupDmTargetConfigured(account: ResolvedSlackAccount, channelId: string): boolean { +function isSlackGroupDmTargetConfigured( + account: ResolvedSlackAccount, + channelId: string, + teamId?: string, +): boolean { const entries = account.config.dm?.groupChannels ?? []; if (entries.length === 0) { return true; } + const candidates = new Set( + buildSlackChannelIdCandidates(channelId, teamId, { + allowUnscoped: getSlackInstallationKind(account.accountId) !== "enterprise", + }).map((candidate) => candidate.toLowerCase()), + ); const target = channelId.trim().toLowerCase(); return entries.some((entry) => { const candidate = String(entry).trim().toLowerCase(); return ( candidate === "*" || + candidates.has(candidate) || candidate === target || candidate === `slack:${target}` || candidate === `channel:${target}` || diff --git a/extensions/slack/src/doctor.test.ts b/extensions/slack/src/doctor.test.ts index 1b8f6615f490..2080b49bf8de 100644 --- a/extensions/slack/src/doctor.test.ts +++ b/extensions/slack/src/doctor.test.ts @@ -174,6 +174,19 @@ describe("slack doctor", () => { ).toBe(true); }); + it("accepts workspace-qualified channel and user ids as stable policy entries", async () => { + const warnings = await collectSlackWarnings({ + allowFrom: ["team:T11111111:user:U01234567"], + channels: { + "team:T11111111:channel:C01234567": { + users: ["team:T11111111:user:U01234567"], + }, + }, + }); + + expect(warnings).toEqual([]); + }); + it("warns for name-keyed allowlist channels but accepts routed ID forms (#81665)", async () => { const warnings = await collectSlackWarnings({ channels: { @@ -183,9 +196,11 @@ describe("slack doctor", () => { c0al2gdua7k: {}, "channel:C0AL2GDUA7L": {}, "channel:c0al2gdua7m": {}, + "team:T11111111:channel:C0AL2GDUA7S": {}, D0AL2GDUA7Q: {}, "channel:d0al2gdua7r": {}, "channel:dabcdefgh": {}, + "team:T11111111:channel:D0AL2GDUA7T": {}, "channel:customers": {}, "CHANNEL:C0AL2GDUA7N": {}, "channel:C0al2gdua7p": {}, @@ -208,10 +223,11 @@ describe("slack doctor", () => { const dmWarnings = warnings.filter((warning) => warning.includes("is a Slack DM conversation ID"), ); - expect(dmWarnings).toHaveLength(3); + expect(dmWarnings).toHaveLength(4); expect(dmWarnings[0]).toContain('channels.slack.channels."D0AL2GDUA7Q"'); expect(dmWarnings[1]).toContain('channels.slack.channels."channel:d0al2gdua7r"'); expect(dmWarnings[2]).toContain('channels.slack.channels."channel:dabcdefgh"'); + expect(dmWarnings[3]).toContain('channels.slack.channels."team:T11111111:channel:D0AL2GDUA7T"'); expect(dmWarnings[0]).toContain("channels.slack.dmPolicy"); }); diff --git a/extensions/slack/src/doctor.ts b/extensions/slack/src/doctor.ts index 177dbf925d91..15524809b900 100644 --- a/extensions/slack/src/doctor.ts +++ b/extensions/slack/src/doctor.ts @@ -14,6 +14,7 @@ import { } from "./doctor-contract.js"; import { probeSlack } from "./probe.js"; import { isSlackMutableAllowEntry } from "./security-doctor.js"; +import { parseSlackTarget } from "./target-parsing.js"; const collectSlackMutableAllowlistWarnings = createDangerousNameMatchingMutableAllowlistWarningCollector({ @@ -45,7 +46,9 @@ const SLACK_CHANNEL_NAME_RE = /^[\p{L}\p{M}\p{N}_-]{1,80}$/u; const SLACK_CHANNEL_NAME_ALPHANUMERIC_RE = /[\p{L}\p{N}]/u; function looksLikeSlackChannelId(channelKey: string): boolean { + const workspaceChannelId = parseWorkspaceQualifiedChannelId(channelKey); return ( + (workspaceChannelId !== undefined && /^[CG]/i.test(workspaceChannelId)) || SLACK_CANONICAL_CHANNEL_ID_RE.test(channelKey) || SLACK_LOWERCASE_CHANNEL_ID_RE.test(channelKey) || SLACK_PREFIXED_CANONICAL_CHANNEL_ID_RE.test(channelKey) || @@ -54,11 +57,26 @@ function looksLikeSlackChannelId(channelKey: string): boolean { } function looksLikeSlackDmId(channelKey: string): boolean { + const workspaceChannelId = parseWorkspaceQualifiedChannelId(channelKey); return ( - SLACK_CANONICAL_DM_ID_RE.test(channelKey) || SLACK_PREFIXED_LOWERCASE_DM_ID_RE.test(channelKey) + (workspaceChannelId !== undefined && /^D/i.test(workspaceChannelId)) || + SLACK_CANONICAL_DM_ID_RE.test(channelKey) || + SLACK_PREFIXED_LOWERCASE_DM_ID_RE.test(channelKey) ); } +function parseWorkspaceQualifiedChannelId(channelKey: string): string | undefined { + if (!/^team:/i.test(channelKey)) { + return undefined; + } + try { + const target = parseSlackTarget(channelKey); + return target?.kind === "channel" && target.teamId ? target.id : undefined; + } catch { + return undefined; + } +} + function looksLikeSlackChannelNameKey(channelKey: string): boolean { const name = channelKey.startsWith("#") ? channelKey.slice(1) : channelKey; return ( diff --git a/extensions/slack/src/group-policy.test.ts b/extensions/slack/src/group-policy.test.ts index a1a84436858d..b81faad5fd53 100644 --- a/extensions/slack/src/group-policy.test.ts +++ b/extensions/slack/src/group-policy.test.ts @@ -2,6 +2,7 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; import { describe, expect, it } from "vitest"; import { resolveSlackGroupRequireMention, resolveSlackGroupToolPolicy } from "./group-policy.js"; +import { registerSlackInstallationState } from "./installation-identity-state.js"; const cfg = { channels: { @@ -100,6 +101,94 @@ describe("slack group policy", () => { }, ); + it("scopes Enterprise mention and tool policies to the event workspace", () => { + const installationState = registerSlackInstallationState("default", "enterprise"); + const enterpriseCfg = { + channels: { + slack: { + channels: { + "team:T11111111:channel:C01234567": { + requireMention: false, + tools: { allow: ["message.send"] }, + }, + "team:T22222222:channel:C01234567": { + requireMention: true, + tools: { deny: ["exec"] }, + }, + }, + }, + }, + } as OpenClawConfig; + + try { + expect( + resolveSlackGroupRequireMention({ + cfg: enterpriseCfg, + groupId: "C01234567", + groupSpace: "T11111111", + }), + ).toBe(false); + expect( + resolveSlackGroupToolPolicy({ + cfg: enterpriseCfg, + groupId: "C01234567", + groupSpace: "T11111111", + }), + ).toEqual({ allow: ["message.send"] }); + expect( + resolveSlackGroupRequireMention({ + cfg: enterpriseCfg, + groupId: "C01234567", + groupSpace: "T22222222", + }), + ).toBe(true); + expect( + resolveSlackGroupToolPolicy({ + cfg: enterpriseCfg, + groupId: "C01234567", + groupSpace: "T22222222", + }), + ).toEqual({ deny: ["exec"] }); + } finally { + installationState.release(); + } + }); + + it("retains bare channel policy matching for workspace installs", () => { + const installationState = registerSlackInstallationState("default", "workspace"); + const workspaceCfg = { + channels: { + slack: { + channels: { + C01234567: { + requireMention: false, + tools: { allow: ["message.send"] }, + }, + }, + }, + }, + } as OpenClawConfig; + + try { + expect( + resolveSlackGroupRequireMention({ + cfg: workspaceCfg, + groupId: "C01234567", + groupSpace: "T11111111", + }), + ).toBe(false); + expect( + resolveSlackGroupToolPolicy({ + cfg: workspaceCfg, + groupId: "C01234567", + groupSpace: "T11111111", + }), + ).toEqual({ allow: ["message.send"] }); + } finally { + installationState.release(); + } + }); + it("prefers the exact channel ID when case variants have different policies", () => { const caseSensitiveCfg = { channels: { diff --git a/extensions/slack/src/group-policy.ts b/extensions/slack/src/group-policy.ts index f357c79e0703..7b9dd1e8a607 100644 --- a/extensions/slack/src/group-policy.ts +++ b/extensions/slack/src/group-policy.ts @@ -12,6 +12,7 @@ import { import { buildChannelKeyCandidates } from "openclaw/plugin-sdk/channel-targets"; import { normalizeHyphenSlug } from "openclaw/plugin-sdk/string-normalization-runtime"; import { mergeSlackAccountConfig, resolveDefaultSlackAccountId } from "./accounts.js"; +import { getSlackInstallationKind } from "./installation-identity-state.js"; type SlackChannelPolicyEntry = { requireMention?: boolean; @@ -19,15 +20,31 @@ type SlackChannelPolicyEntry = { toolsBySender?: GroupToolPolicyBySenderConfig; }; -export function buildSlackChannelIdCandidates(channelId: string | null | undefined): string[] { +export function buildSlackChannelIdCandidates( + channelId: string | null | undefined, + teamId?: string | null, + options?: { allowUnscoped?: boolean }, +): string[] { const trimmedId = channelId?.trim(); if (!trimmedId) { return []; } const lowercaseId = trimmedId.toLowerCase(); const uppercaseId = trimmedId.toUpperCase(); + const exactTeamId = teamId || undefined; + const lowercaseTeamId = exactTeamId?.toLowerCase(); + const uppercaseTeamId = exactTeamId?.toUpperCase(); // Inbound Slack IDs are uppercase, but persisted session group IDs are lowercase. + const scopedCandidates = buildChannelKeyCandidates( + exactTeamId ? `team:${exactTeamId}:channel:${trimmedId}` : undefined, + lowercaseTeamId ? `team:${lowercaseTeamId}:channel:${lowercaseId}` : undefined, + uppercaseTeamId ? `team:${uppercaseTeamId}:channel:${uppercaseId}` : undefined, + ); + if (exactTeamId && options?.allowUnscoped !== true) { + return scopedCandidates; + } return buildChannelKeyCandidates( + ...scopedCandidates, trimmedId, lowercaseId, uppercaseId, @@ -69,8 +86,9 @@ function resolveSlackGroupPolicyScope(params: ChannelGroupContext) { | Record | undefined; const channelName = params.groupChannel?.replace(/^#/, ""); + const allowUnscoped = getSlackInstallationKind(accountId) !== "enterprise"; const candidates = buildChannelKeyCandidates( - ...buildSlackChannelIdCandidates(params.groupId), + ...buildSlackChannelIdCandidates(params.groupId, params.groupSpace, { allowUnscoped }), channelName ? `#${channelName}` : undefined, channelName, normalizeHyphenSlug(channelName), diff --git a/extensions/slack/src/monitor/allow-list.test.ts b/extensions/slack/src/monitor/allow-list.test.ts index 3761b12342f4..a056a8c0402c 100644 --- a/extensions/slack/src/monitor/allow-list.test.ts +++ b/extensions/slack/src/monitor/allow-list.test.ts @@ -63,4 +63,65 @@ describe("slack/allow-list", () => { false, ); }); + + it("matches a workspace-qualified user only in that workspace", () => { + const allowList = ["team:t11111111:user:u01234567"]; + + expect( + resolveSlackAllowListMatch({ + allowList, + teamId: "T11111111", + id: "U01234567", + }), + ).toEqual({ + allowed: true, + matchKey: "team:t11111111:user:u01234567", + matchSource: "workspace-id", + }); + expect( + resolveSlackAllowListMatch({ + allowList, + teamId: "T22222222", + id: "U01234567", + }), + ).toEqual({ allowed: false }); + expect( + resolveSlackAllowListMatch({ + allowList: ["u01234567"], + teamId: "T22222222", + id: "U01234567", + }), + ).toEqual({ allowed: false }); + expect( + resolveSlackAllowListMatch({ + allowList: ["u01234567"], + teamId: "T22222222", + id: "U01234567", + allowUnscoped: true, + }), + ).toEqual({ allowed: true, matchKey: "u01234567", matchSource: "id" }); + }); + + it("matches a workspace-qualified bot only in that workspace", () => { + const allowList = ["team:t11111111:user:b01234567"]; + + expect( + resolveSlackAllowListMatch({ + allowList, + teamId: "T11111111", + id: "B01234567", + }), + ).toEqual({ + allowed: true, + matchKey: "team:t11111111:user:b01234567", + matchSource: "workspace-id", + }); + expect( + resolveSlackAllowListMatch({ + allowList, + teamId: "T22222222", + id: "B01234567", + }), + ).toEqual({ allowed: false }); + }); }); diff --git a/extensions/slack/src/monitor/allow-list.ts b/extensions/slack/src/monitor/allow-list.ts index 6281629a62b5..c184f1b59624 100644 --- a/extensions/slack/src/monitor/allow-list.ts +++ b/extensions/slack/src/monitor/allow-list.ts @@ -10,6 +10,7 @@ import { normalizeStringEntries, normalizeStringEntriesLower, } from "openclaw/plugin-sdk/string-normalization-runtime"; +import { parseSlackTarget } from "../target-parsing.js"; const SLACK_SLUG_CACHE_MAX = 512; const slackSlugCache = new Map(); @@ -44,26 +45,50 @@ export function normalizeSlackAllowOwnerEntry(entry: string): string | undefined if (!trimmed || trimmed === "*") { return undefined; } + try { + const target = parseSlackTarget(trimmed); + if (target?.kind === "user" && target.teamId) { + return target.id.toLowerCase(); + } + } catch { + return undefined; + } const withoutPrefix = trimmed.replace(/^(slack:|user:)/, ""); return /^u[a-z0-9]+$/.test(withoutPrefix) ? withoutPrefix : undefined; } export type SlackAllowListMatch = AllowlistMatch< - "wildcard" | "id" | "prefixed-id" | "prefixed-user" | "name" | "prefixed-name" | "slug" + | "wildcard" + | "workspace-id" + | "id" + | "prefixed-id" + | "prefixed-user" + | "name" + | "prefixed-name" + | "slug" >; type SlackAllowListSource = Exclude; export function resolveSlackAllowListMatch(params: { allowList: readonly string[]; + teamId?: string; id?: string; name?: string; allowNameMatching?: boolean; + allowUnscoped?: boolean; }): SlackAllowListMatch { const compiledAllowList = compileAllowlist(params.allowList); + const teamId = normalizeOptionalLowercaseString(params.teamId); const id = normalizeOptionalLowercaseString(params.id); const name = normalizeOptionalLowercaseString(params.name); const slug = normalizeSlackSlug(name); - const candidates: Array<{ value?: string; source: SlackAllowListSource }> = [ + const scopedCandidates: Array<{ value?: string; source: SlackAllowListSource }> = [ + { + value: teamId && id ? `team:${teamId}:user:${id}` : undefined, + source: "workspace-id", + }, + ]; + const unscopedCandidates: Array<{ value?: string; source: SlackAllowListSource }> = [ { value: id, source: "id" }, { value: id ? `slack:${id}` : undefined, source: "prefixed-id" }, { value: id ? `user:${id}` : undefined, source: "prefixed-user" }, @@ -75,6 +100,10 @@ export function resolveSlackAllowListMatch(params: { ] satisfies Array<{ value?: string; source: SlackAllowListSource }>) : []), ]; + const candidates = + teamId && params.allowUnscoped !== true + ? scopedCandidates + : [...scopedCandidates, ...unscopedCandidates]; return resolveCompiledAllowlistMatch({ compiledAllowlist: compiledAllowList, candidates, @@ -83,18 +112,22 @@ export function resolveSlackAllowListMatch(params: { export function allowListMatches(params: { allowList: string[]; + teamId?: string; id?: string; name?: string; allowNameMatching?: boolean; + allowUnscoped?: boolean; }) { return resolveSlackAllowListMatch(params).allowed; } export function resolveSlackUserAllowed(params: { allowList?: Array; + teamId?: string; userId?: string; userName?: string; allowNameMatching?: boolean; + allowUnscoped?: boolean; }) { const allowList = normalizeAllowListLower(params.allowList); if (allowList.length === 0) { @@ -102,8 +135,37 @@ export function resolveSlackUserAllowed(params: { } return allowListMatches({ allowList, + teamId: params.teamId, id: params.userId, name: params.userName, allowNameMatching: params.allowNameMatching, + allowUnscoped: params.allowUnscoped, + }); +} + +export function resolveSlackUserAllowListForTeam(params: { + allowList?: Array; + teamId?: string; + preserveUnmatchedScopedEntries?: boolean; + allowUnscoped?: boolean; +}): string[] { + const allowList = normalizeAllowListLower(params.allowList); + const teamId = normalizeOptionalLowercaseString(params.teamId); + return allowList.flatMap((entry) => { + if (entry === "*") { + return [entry]; + } + if (!entry.startsWith("team:")) { + return params.allowUnscoped === true || params.preserveUnmatchedScopedEntries ? [entry] : []; + } + try { + const target = parseSlackTarget(entry); + if (target?.kind === "user" && target.teamId?.toLowerCase() === teamId) { + return params.allowUnscoped === true ? [target.id.toLowerCase()] : [entry]; + } + return params.preserveUnmatchedScopedEntries ? [entry] : []; + } catch { + return params.preserveUnmatchedScopedEntries ? [entry] : []; + } }); } diff --git a/extensions/slack/src/monitor/auth.test.ts b/extensions/slack/src/monitor/auth.test.ts index d9b716446fd6..a7845cfc366e 100644 --- a/extensions/slack/src/monitor/auth.test.ts +++ b/extensions/slack/src/monitor/auth.test.ts @@ -53,6 +53,7 @@ function makeAuthorizeCtx(params?: { resolveChannelName?: ( channelId: string, ) => Promise<{ name?: string; type?: "im" | "mpim" | "channel" | "group" }>; + installationIdentity?: SlackMonitorContext["installationIdentity"]; }) { return { allowFrom: params?.allowFrom ?? [], @@ -63,6 +64,10 @@ function makeAuthorizeCtx(params?: { channelsConfig: params?.channelsConfig ?? {}, channelsConfigKeys: Object.keys(params?.channelsConfig ?? {}), defaultRequireMention: true, + installationIdentity: params?.installationIdentity ?? { + kind: "workspace", + teamId: "T_MAIN", + }, isChannelAllowed: vi.fn(() => true), resolveUserName: vi.fn( params?.resolveUserName ?? ((_) => Promise.resolve({ name: undefined })), @@ -184,16 +189,33 @@ describe("resolveSlackEffectiveAllowFrom", () => { includePairingStore: true, eventScope: { teamId: "T11111111", client: {} as never }, }), - ).resolves.toEqual(["uconfig123", "u11111111"]); + ).resolves.toEqual(["team:t11111111:user:u11111111"]); await expect( resolveSlackEffectiveAllowFrom(ctx, { includePairingStore: true, eventScope: { teamId: "T22222222", client: {} as never }, }), - ).resolves.toEqual(["uconfig123", "u22222222"]); + ).resolves.toEqual(["team:t22222222:user:u22222222"]); await expect( resolveSlackEffectiveAllowFrom(ctx, { includePairingStore: true }), - ).resolves.toEqual(["uconfig123"]); + ).resolves.toEqual([]); + }); + + it("keeps only configured users for the current Enterprise workspace", async () => { + const ctx = makeSlackCtx(["team:T11111111:user:U01234567"]); + ctx.installationIdentity = { kind: "enterprise", enterpriseId: "E11111111" }; + + await expect( + resolveSlackEffectiveAllowFrom(ctx, { + eventScope: { teamId: "T11111111", client: {} as never }, + }), + ).resolves.toEqual(["team:t11111111:user:u01234567"]); + await expect( + resolveSlackEffectiveAllowFrom(ctx, { + eventScope: { teamId: "T22222222", client: {} as never }, + }), + ).resolves.toEqual([]); + await expect(resolveSlackEffectiveAllowFrom(ctx)).resolves.toEqual([]); }); }); @@ -402,6 +424,47 @@ describe("authorizeSlackSystemEventSender", () => { }); describe("resolveSlackCommandIngress", () => { + it.each([ + ["allows the workspace-qualified user in its workspace", "T11111111", "allow", true], + ["blocks the same bare user ID in another workspace", "T22222222", "block", false], + ] as const)("%s", async (_name, teamId, decision, allowed) => { + const result = await resolveSlackCommandIngress({ + ctx: makeAuthorizeCtx({ + installationIdentity: { kind: "enterprise", enterpriseId: "E11111111" }, + }), + teamId, + senderId: "U01234567", + channelType: "channel", + channelId: "C01234567", + ownerAllowFromLower: [], + channelUsers: ["team:T11111111:user:U01234567"], + allowTextCommands: false, + hasControlCommand: false, + }); + + expect(result.senderAccess.decision).toBe(decision); + expect(result.senderAccess.gate?.allowed).toBe(allowed); + }); + + it("does not authorize a bare user ID for an Enterprise workspace event", async () => { + const result = await resolveSlackCommandIngress({ + ctx: makeAuthorizeCtx({ + installationIdentity: { kind: "enterprise", enterpriseId: "E11111111" }, + }), + teamId: "T11111111", + senderId: "U01234567", + channelType: "channel", + channelId: "C01234567", + ownerAllowFromLower: [], + channelUsers: ["U01234567"], + allowTextCommands: false, + hasControlCommand: false, + }); + + expect(result.senderAccess.decision).toBe("block"); + expect(result.senderAccess.gate?.allowed).toBe(false); + }); + it("does not authorize commands when sender denial stops before the command gate", async () => { const result = await resolveSlackCommandIngress({ ctx: makeAuthorizeCtx(), diff --git a/extensions/slack/src/monitor/auth.ts b/extensions/slack/src/monitor/auth.ts index bf837c1056e5..32442020ff30 100644 --- a/extensions/slack/src/monitor/auth.ts +++ b/extensions/slack/src/monitor/auth.ts @@ -19,10 +19,10 @@ import { collectSlackCursorPages } from "../cursor-pages.js"; import { parseSlackTarget } from "../target-parsing.js"; import { allowListMatches, - normalizeAllowList, normalizeAllowListLower, normalizeSlackAllowOwnerEntry, normalizeSlackSlug, + resolveSlackUserAllowListForTeam, } from "./allow-list.js"; import { resolveSlackChannelConfig } from "./channel-config.js"; import { inferSlackChannelType } from "./channel-type.js"; @@ -80,6 +80,14 @@ function normalizeSlackStableEntry(entry: string): string | null { if (!normalized) { return null; } + try { + const target = parseSlackTarget(normalized); + if (target?.kind === "user" && target.teamId) { + return target.normalized; + } + } catch { + return null; + } const userId = normalizeSlackUserId(normalized); return isSlackStableUserId(userId) ? userId : null; } @@ -126,8 +134,17 @@ const slackIngressIdentity = defineStableChannelIngressIdentity({ })), }); -function createSlackIngressSubject(params: { senderId: string; senderName?: string }) { - const senderId = normalizeSlackUserId(params.senderId); +function createSlackIngressSubject(params: { + senderId: string; + senderName?: string; + teamId?: string; + workspaceScoped?: boolean; +}) { + const bareSenderId = normalizeSlackUserId(params.senderId); + const senderId = + params.workspaceScoped && params.teamId + ? `team:${params.teamId.toLowerCase()}:user:${bareSenderId}` + : bareSenderId; const senderName = params.senderName?.trim().toLowerCase(); const senderNameSlug = senderName ? normalizeSlackSlug(senderName) : undefined; return { @@ -179,15 +196,20 @@ function pruneChannelMembersCache(cache: Map { try { const target = parseSlackTarget(entry); - return target?.kind === "user" && target.teamId?.toLowerCase() === teamId ? [target.id] : []; + return target?.kind === "user" && target.teamId?.toLowerCase() === normalizedTeamId + ? [entry] + : []; } catch { return []; } @@ -318,9 +346,11 @@ export async function authorizeSlackBotRoomMessage(params: { channelUserAllowList.length > 0 && allowListMatches({ allowList: channelUserAllowList, + teamId: params.eventScope?.teamId ?? params.ctx.teamId, id: params.senderId, name: params.senderName, allowNameMatching: params.ctx.allowNameMatching, + allowUnscoped: params.ctx.installationIdentity?.kind !== "enterprise", }) ) { return true; @@ -366,6 +396,7 @@ function slackIngressConversationKind( export async function resolveSlackCommandIngress(params: { ctx: SlackMonitorContext; + teamId?: string; senderId: string; senderName?: string; channelType: SlackIngressChannelType; @@ -383,19 +414,29 @@ export async function resolveSlackCommandIngress(params: { }) { const isDirectMessage = params.channelType === "im"; const isGroupDm = params.channelType === "mpim"; - const channelUsers = normalizeAllowListLower(params.channelUsers); - const channelUsersConfigured = !isDirectMessage && !isGroupDm && channelUsers.length > 0; + const teamId = params.teamId ?? params.ctx.teamId; + const allowUnscoped = params.ctx.installationIdentity?.kind !== "enterprise"; + const ownerAllowFrom = resolveSlackUserAllowListForTeam({ + allowList: params.ownerAllowFromLower, + teamId, + allowUnscoped, + }); + const channelUsers = resolveSlackUserAllowListForTeam({ + allowList: params.channelUsers, + teamId, + allowUnscoped, + }); + const channelUsersConfigured = + !isDirectMessage && !isGroupDm && normalizeAllowListLower(params.channelUsers).length > 0; // MPIM ingress is group-shaped, but its sender policy is DM-owned. Callers // pass configured allowFrom without pairing-store approvals for this path. - const groupAllowFrom = isGroupDm - ? params.ownerAllowFromLower - : channelUsersConfigured - ? channelUsers - : []; + const groupAllowFrom = isGroupDm ? ownerAllowFrom : channelUsersConfigured ? channelUsers : []; const result = await createSlackIngressResolver(params.ctx).message({ subject: createSlackIngressSubject({ senderId: params.senderId, senderName: params.senderName, + teamId, + workspaceScoped: !allowUnscoped, }), conversation: { kind: slackIngressConversationKind(params.channelType), @@ -414,13 +455,13 @@ export async function resolveSlackCommandIngress(params: { ...(params.activation ? { activation: params.activation } : {}), }, mentionFacts: params.mentionFacts, - allowFrom: isDirectMessage ? ["*"] : params.ownerAllowFromLower, + allowFrom: isDirectMessage ? ["*"] : ownerAllowFrom, groupAllowFrom, command: { allowTextCommands: params.allowTextCommands, hasControlCommand: params.hasControlCommand, modeWhenAccessGroupsOff: params.modeWhenAccessGroupsOff, - ...(isDirectMessage ? { commandOwnerAllowFrom: params.ownerAllowFromLower } : {}), + ...(isDirectMessage ? { commandOwnerAllowFrom: ownerAllowFrom } : {}), }, }); return result; @@ -428,6 +469,7 @@ export async function resolveSlackCommandIngress(params: { async function decideSlackSystemIngress(params: { ctx: SlackMonitorContext; + teamId?: string; senderId: string; senderName?: string; channelType: SlackIngressChannelType; @@ -438,12 +480,24 @@ async function decideSlackSystemIngress(params: { }): Promise { const isDirectMessage = params.channelType === "im"; const isGroupDm = params.channelType === "mpim"; - const channelUsers = normalizeAllowListLower(params.channelUsers); - const channelUsersConfigured = !isDirectMessage && !isGroupDm && channelUsers.length > 0; + const teamId = params.teamId ?? params.ctx.teamId; + const allowUnscoped = params.ctx.installationIdentity?.kind !== "enterprise"; + const ownerAllowFromLower = resolveSlackUserAllowListForTeam({ + allowList: params.ownerAllowFromLower, + teamId, + allowUnscoped, + }); + const channelUsers = resolveSlackUserAllowListForTeam({ + allowList: params.channelUsers, + teamId, + allowUnscoped, + }); + const channelUsersConfigured = + !isDirectMessage && !isGroupDm && normalizeAllowListLower(params.channelUsers).length > 0; const ownerAllowFrom = params.interactiveEvent && channelUsersConfigured - ? params.ownerAllowFromLower.filter((entry) => entry !== "*") - : params.ownerAllowFromLower; + ? ownerAllowFromLower.filter((entry) => entry !== "*") + : ownerAllowFromLower; const hasAnyCommandAllowlist = ownerAllowFrom.length > 0 || channelUsersConfigured; const groupAllowFrom = (() => { if (isDirectMessage) { @@ -458,12 +512,14 @@ async function decideSlackSystemIngress(params: { if (channelUsersConfigured) { return channelUsers; } - return params.channelId ? ["*"] : wildcardWhenOpen(params.ownerAllowFromLower); + return params.channelId ? ["*"] : wildcardWhenOpen(ownerAllowFromLower); })(); const result = await createSlackIngressResolver(params.ctx).message({ subject: createSlackIngressSubject({ senderId: params.senderId, senderName: params.senderName, + teamId, + workspaceScoped: !allowUnscoped, }), conversation: { kind: slackIngressConversationKind(params.channelType), @@ -479,14 +535,14 @@ async function decideSlackSystemIngress(params: { ? "allowlist" : params.interactiveEvent && hasAnyCommandAllowlist ? "open" - : channelUsersConfigured || (!params.channelId && params.ownerAllowFromLower.length > 0) + : channelUsersConfigured || (!params.channelId && ownerAllowFromLower.length > 0) ? "allowlist" : "open", policy: { groupAllowFromFallbackToAllowFrom: false, mutableIdentifierMatching: params.ctx.allowNameMatching ? "enabled" : "disabled", }, - allowFrom: isDirectMessage ? wildcardWhenOpen(params.ownerAllowFromLower) : ownerAllowFrom, + allowFrom: isDirectMessage ? wildcardWhenOpen(ownerAllowFromLower) : ownerAllowFrom, groupAllowFrom, command: params.interactiveEvent && hasAnyCommandAllowlist @@ -541,6 +597,7 @@ export async function authorizeSlackSystemEventSender(params: { channelType = normalizeSlackChannelType(resolvedTypeSource, channelId); if ( !params.ctx.isChannelAllowed({ + teamId: params.eventScope?.teamId ?? params.ctx.teamId, channelId, channelName, channelType, @@ -598,6 +655,8 @@ export async function authorizeSlackSystemEventSender(params: { }); const channelConfig = channelId ? resolveSlackChannelConfig({ + teamId: params.eventScope?.teamId ?? params.ctx.teamId, + allowUnscoped: params.ctx.installationIdentity?.kind !== "enterprise", channelId, channelName, channels: params.ctx.channelsConfig, @@ -610,6 +669,7 @@ export async function authorizeSlackSystemEventSender(params: { Array.isArray(channelConfig?.users) && channelConfig.users.length > 0; const decision = await decideSlackSystemIngress({ ctx: params.ctx, + teamId: params.eventScope?.teamId ?? params.ctx.teamId, senderId, senderName, channelType: ingressChannelType, diff --git a/extensions/slack/src/monitor/channel-config.ts b/extensions/slack/src/monitor/channel-config.ts index 4064b1fc8b39..c4c6be5e2575 100644 --- a/extensions/slack/src/monitor/channel-config.ts +++ b/extensions/slack/src/monitor/channel-config.ts @@ -11,7 +11,7 @@ import type { } from "openclaw/plugin-sdk/config-contracts"; import { mergePairLoopGuardConfig } from "openclaw/plugin-sdk/pair-loop-guard-runtime"; import { buildSlackChannelIdCandidates, buildSlackChannelPolicyScope } from "../group-policy.js"; -import { normalizeSlackSlug } from "./allow-list.js"; +import { normalizeSlackSlug, resolveSlackUserAllowListForTeam } from "./allow-list.js"; export type SlackChannelConfigResolved = { allowed: boolean; @@ -63,6 +63,8 @@ export function resolveSlackChannelLabel(params: { channelId?: string; channelNa } export function resolveSlackChannelConfig(params: { + teamId?: string; + allowUnscoped?: boolean; channelId: string; channelName?: string; channels?: SlackChannelConfigEntries; @@ -83,7 +85,9 @@ export function resolveSlackChannelConfig(params: { const normalizedName = channelName ? normalizeSlackSlug(channelName) : ""; const directName = channelName ? channelName.trim() : ""; const candidates = buildChannelKeyCandidates( - ...buildSlackChannelIdCandidates(channelId), + ...buildSlackChannelIdCandidates(channelId, params.teamId, { + allowUnscoped: params.allowUnscoped, + }), allowNameMatching ? (channelName ? `#${directName}` : undefined) : undefined, allowNameMatching ? directName : undefined, allowNameMatching ? normalizedName : undefined, @@ -115,7 +119,14 @@ export function resolveSlackChannelConfig(params: { fallback?.botLoopProtection, matched?.botLoopProtection, ); - const users = firstDefined(resolved.users, fallback?.users); + const users = resolveSlackUserAllowListForTeam({ + allowList: firstDefined(resolved.users, fallback?.users), + teamId: params.teamId, + allowUnscoped: params.allowUnscoped, + // Keeping unmatched entries preserves the configured allowlist gate; strict + // workspace ingress treats bare and differently scoped values as non-matching. + preserveUnmatchedScopedEntries: true, + }); const skills = firstDefined(resolved.skills, fallback?.skills); const systemPrompt = firstDefined(resolved.systemPrompt, fallback?.systemPrompt); const presenceEvents = firstDefined(resolved.presenceEvents, fallback?.presenceEvents); @@ -126,7 +137,7 @@ export function resolveSlackChannelConfig(params: { replyToMode, allowBots, botLoopProtection, - users, + users: users.length > 0 ? users : undefined, skills, systemPrompt, presenceEvents, diff --git a/extensions/slack/src/monitor/context.test.ts b/extensions/slack/src/monitor/context.test.ts index f17e77a9932e..e8547d32f3b3 100644 --- a/extensions/slack/src/monitor/context.test.ts +++ b/extensions/slack/src/monitor/context.test.ts @@ -13,6 +13,7 @@ function createTestContext(params?: { groupDmChannels?: string[]; appClient?: App["client"]; apiAppId?: string; + channelsConfig?: Record; }) { return createSlackMonitorContext({ cfg: { @@ -38,6 +39,7 @@ function createTestContext(params?: { groupDmEnabled: params?.groupDmEnabled ?? false, groupDmChannels: params?.groupDmChannels ?? [], defaultRequireMention: true, + channelsConfig: params?.channelsConfig, groupPolicy: "allowlist", useAccessGroups: true, reactionMode: "off", @@ -150,6 +152,46 @@ describe("createSlackMonitorContext isChannelAllowed", () => { expect(ctx.isChannelAllowed({ channelId: "G456", channelType: "mpim" })).toBe(true); expect(ctx.isChannelAllowed({ channelId: "G999", channelType: "mpim" })).toBe(false); }); + + it("matches workspace-qualified channel and group DM policies", () => { + const ctx = createTestContext({ + groupDmEnabled: true, + groupDmChannels: ["team:T11111111:channel:G01234567"], + channelsConfig: { + "team:T11111111:channel:C01234567": { enabled: true }, + "team:T22222222:channel:C01234567": { enabled: false }, + }, + }); + + expect( + ctx.isChannelAllowed({ + teamId: "T11111111", + channelId: "C01234567", + channelType: "channel", + }), + ).toBe(true); + expect( + ctx.isChannelAllowed({ + teamId: "T22222222", + channelId: "C01234567", + channelType: "channel", + }), + ).toBe(false); + expect( + ctx.isChannelAllowed({ + teamId: "T11111111", + channelId: "G01234567", + channelType: "mpim", + }), + ).toBe(true); + expect( + ctx.isChannelAllowed({ + teamId: "T22222222", + channelId: "G01234567", + channelType: "mpim", + }), + ).toBe(false); + }); }); describe("createSlackMonitorContext resolveSlackSystemEventSessionKey", () => { diff --git a/extensions/slack/src/monitor/context.ts b/extensions/slack/src/monitor/context.ts index 9b8d900a8852..51957f07f7e2 100644 --- a/extensions/slack/src/monitor/context.ts +++ b/extensions/slack/src/monitor/context.ts @@ -18,6 +18,7 @@ import { normalizeOptionalString, } from "openclaw/plugin-sdk/string-coerce-runtime"; import { formatSlackError } from "../errors.js"; +import { buildSlackChannelIdCandidates } from "../group-policy.js"; import type { SlackMessageEvent } from "../types.js"; import { createSlackAgentViewState } from "./agent-view-state.js"; import { normalizeAllowList, normalizeAllowListLower, normalizeSlackSlug } from "./allow-list.js"; @@ -116,6 +117,7 @@ export type SlackMonitorContext = { eventScope?: SlackEventScope; }) => string; isChannelAllowed: (params: { + teamId?: string; channelId?: string; channelName?: string; channelType?: SlackMessageEvent["channel_type"]; @@ -374,6 +376,7 @@ export function createSlackMonitorContext(params: { }); const isChannelAllowed = (p: { + teamId?: string; channelId?: string; channelName?: string; channelType?: SlackMessageEvent["channel_type"]; @@ -392,7 +395,9 @@ export function createSlackMonitorContext(params: { if (isGroupDm && groupDmChannels.length > 0) { const candidates = [ - p.channelId, + ...buildSlackChannelIdCandidates(p.channelId, p.teamId, { + allowUnscoped: params.installationIdentity?.kind !== "enterprise", + }), p.channelName ? `#${p.channelName}` : undefined, p.channelName, p.channelName ? normalizeSlackSlug(p.channelName) : undefined, @@ -409,6 +414,8 @@ export function createSlackMonitorContext(params: { if (isRoom && p.channelId) { const channelConfig = resolveSlackChannelConfig({ + teamId: p.teamId, + allowUnscoped: params.installationIdentity?.kind !== "enterprise", channelId: p.channelId, channelName: p.channelName, channels: params.channelsConfig, @@ -433,7 +440,7 @@ export function createSlackMonitorContext(params: { if (shouldDrop) { if (explicitlyDisabled) { const reason = "channel_not_allowed"; - const warningKey = `${params.accountId}:${p.channelId}:${reason}`; + const warningKey = `${params.accountId}:${p.teamId ? `${p.teamId}:` : ""}${p.channelId}:${reason}`; if (!channelDenialWarnings.peek(warningKey)) { channelDenialWarnings.check(warningKey); logger.warn( diff --git a/extensions/slack/src/monitor/dm-auth.test.ts b/extensions/slack/src/monitor/dm-auth.test.ts index e9df4881181b..acee17596483 100644 --- a/extensions/slack/src/monitor/dm-auth.test.ts +++ b/extensions/slack/src/monitor/dm-auth.test.ts @@ -76,6 +76,31 @@ describe("authorizeSlackDirectMessage", () => { }); }); + it("allows bare user ids for workspace-install DMs", async () => { + const params = makeParams("allowlist"); + params.ctx.installationIdentity = { kind: "workspace", teamId: "T11111111" }; + params.eventScope = { teamId: "T11111111", client: {} as never }; + params.allowFromLower = ["u123"]; + + await expect(authorizeSlackDirectMessage(params)).resolves.toBe(true); + + expect(params.onUnauthorized).not.toHaveBeenCalled(); + }); + + it("keeps bare user ids scoped out of Enterprise DMs", async () => { + const params = makeParams("allowlist"); + params.ctx.installationIdentity = { kind: "enterprise", enterpriseId: "E11111111" }; + params.eventScope = { teamId: "T11111111", client: {} as never }; + params.allowFromLower = ["u123"]; + + await expect(authorizeSlackDirectMessage(params)).resolves.toBe(false); + + expect(params.onUnauthorized).toHaveBeenCalledWith({ + allowMatchMeta: "matchKey=none matchSource=none", + senderName: "Alice", + }); + }); + it("creates independent pairing requests for the same user in two Grid workspaces", async () => { const pendingCodes = new Map(); upsertChannelPairingRequestMock.mockImplementation( diff --git a/extensions/slack/src/monitor/dm-auth.ts b/extensions/slack/src/monitor/dm-auth.ts index 26371566796f..53b5b9a9c117 100644 --- a/extensions/slack/src/monitor/dm-auth.ts +++ b/extensions/slack/src/monitor/dm-auth.ts @@ -33,9 +33,11 @@ export async function authorizeSlackDirectMessage(params: { const senderName = sender?.name ?? undefined; const allowMatch = resolveSlackAllowListMatch({ allowList: params.allowFromLower, + teamId: params.eventScope?.teamId ?? params.ctx.teamId, id: params.senderId, name: senderName, allowNameMatching: params.ctx.allowNameMatching, + allowUnscoped: params.ctx.installationIdentity?.kind !== "enterprise", }); const allowMatchMeta = formatAllowlistMatchMeta(allowMatch); if (allowMatch.allowed) { diff --git a/extensions/slack/src/monitor/enterprise-install.test.ts b/extensions/slack/src/monitor/enterprise-install.test.ts index 8ae556e21445..51f6b4796e90 100644 --- a/extensions/slack/src/monitor/enterprise-install.test.ts +++ b/extensions/slack/src/monitor/enterprise-install.test.ts @@ -93,16 +93,18 @@ describe("assertEnterpriseSlackPolicyConfig", () => { assertEnterpriseSlackPolicyConfig({ accountId: "org", config: { - allowFrom: ["U01234567", "slack:W01234567", "user:U12345678"], - dm: { groupChannels: ["G01234567", "channel:G12345678"] }, + allowFrom: ["team:T01234567:user:U01234567"], + dm: { + groupChannels: ["team:T01234567:channel:G01234567"], + }, mentionPatterns: { mode: "allow", allowIn: ["team:T01234567:channel:C01234567"], denyIn: ["team:T12345678:channel:C12345678"], }, channels: { - C01234567: { - users: ["U01234567", "slack:W01234567", "user:U12345678"], + "team:T01234567:channel:C01234567": { + users: ["team:T01234567:user:U01234567", "team:T01234567:user:B01234567"], toolsBySender: { U01234567: {}, "id:W01234567": {}, @@ -110,9 +112,11 @@ describe("assertEnterpriseSlackPolicyConfig", () => { "*": {}, }, }, - "channel:C12345678": {}, + "team:T12345678:channel:C12345678": {}, "*": {}, }, + reactionNotifications: "allowlist", + reactionAllowlist: ["team:T01234567:user:U01234567"], }, }), ).not.toThrow(); @@ -139,6 +143,25 @@ describe("assertEnterpriseSlackPolicyConfig", () => { ).toThrow(/cannot use dangerouslyAllowNameMatching/); }); + it.each<[string, SlackAccountConfig]>([ + ["channel ID", { channels: { C01234567: {} } }], + ["allowFrom user ID", { allowFrom: ["U01234567"] }], + ["group DM channel ID", { dm: { groupChannels: ["G01234567"] } }], + ["reaction user ID", { reactionNotifications: "allowlist", reactionAllowlist: ["U01234567"] }], + [ + "per-channel user ID", + { + channels: { + "team:T01234567:channel:C01234567": { users: ["U01234567"] }, + }, + }, + ], + ])("rejects unscoped Enterprise %s", (_label, config) => { + expect(() => assertEnterpriseSlackPolicyConfig({ accountId: "org", config })).toThrow( + /Slack Enterprise Grid/, + ); + }); + it.each<[string, SlackAccountConfig]>([ ["channels key", { channels: { general: {} } }], ["prefixed channels key", { channels: { "channel:general": {} } }], @@ -191,7 +214,7 @@ describe("assertEnterpriseSlackPolicyConfig", () => { accountId: "org", config: { channels: { - C01234567: { + "team:T01234567:channel:C01234567": { toolsBySender: { [entry]: { deny: ["exec"] }, "*": { allow: ["exec"] }, diff --git a/extensions/slack/src/monitor/enterprise-install.ts b/extensions/slack/src/monitor/enterprise-install.ts index 820414378aba..4c6ff7e7ced9 100644 --- a/extensions/slack/src/monitor/enterprise-install.ts +++ b/extensions/slack/src/monitor/enterprise-install.ts @@ -42,9 +42,12 @@ export type SlackAuthTestIdentity = { }; const SLACK_CHANNEL_ID_RE = /^[CDG][A-Z0-9]{8,}$/; -const SLACK_USER_ID_RE = /^[UW][A-Z0-9]{8,}$/; +const SLACK_USER_ID_RE = /^[BUW][A-Z0-9]{8,}$/; -function isStableSlackChannelEntry(value: unknown, options?: { allowWildcard?: boolean }): boolean { +function isWorkspaceScopedSlackChannelEntry( + value: unknown, + options?: { allowWildcard?: boolean }, +): boolean { if (typeof value !== "string") { return false; } @@ -52,14 +55,10 @@ function isStableSlackChannelEntry(value: unknown, options?: { allowWildcard?: b if (normalized === "*") { return options?.allowWildcard === true; } - const prefixed = /^channel:([CDG][A-Z0-9]{8,})$/.exec(normalized); - if (prefixed?.[1]) { - return true; - } - return SLACK_CHANNEL_ID_RE.test(normalized); + return isWorkspaceQualifiedSlackTarget(normalized, "channel"); } -function isStableSlackAllowlistUserEntry(value: unknown): boolean { +function isWorkspaceScopedSlackAllowlistUserEntry(value: unknown): boolean { if (typeof value !== "string") { return false; } @@ -67,8 +66,7 @@ function isStableSlackAllowlistUserEntry(value: unknown): boolean { if (normalized === "*") { return true; } - const prefixed = /^(?:slack|user):([UW][A-Z0-9]{8,})$/.exec(normalized); - return Boolean(prefixed?.[1]) || SLACK_USER_ID_RE.test(normalized); + return isWorkspaceQualifiedSlackTarget(normalized, "user"); } function isStableSlackToolsBySenderEntry(value: unknown): boolean { @@ -137,30 +135,30 @@ export function assertEnterpriseSlackPolicyConfig(params: { assertStableEntries({ values: config.allowFrom, path: `channels.slack.accounts.${accountId}.allowFrom`, - predicate: isStableSlackAllowlistUserEntry, + predicate: isWorkspaceScopedSlackAllowlistUserEntry, }); assertStableEntries({ values: config.dm?.groupChannels, path: `channels.slack.accounts.${accountId}.dm.groupChannels`, - predicate: (value) => isStableSlackChannelEntry(value), + predicate: (value) => isWorkspaceScopedSlackChannelEntry(value), }); if (config.reactionNotifications === "allowlist") { assertStableEntries({ values: config.reactionAllowlist, path: `channels.slack.accounts.${accountId}.reactionAllowlist`, - predicate: isStableSlackAllowlistUserEntry, + predicate: isWorkspaceScopedSlackAllowlistUserEntry, }); } for (const [channelKey, channel] of Object.entries(config.channels ?? {})) { - if (!isStableSlackChannelEntry(channelKey, { allowWildcard: true })) { + if (!isWorkspaceScopedSlackChannelEntry(channelKey, { allowWildcard: true })) { throw new Error( - `Slack Enterprise Grid org installs require stable Slack channel IDs; invalid channels key ${JSON.stringify(channelKey)}`, + `Slack Enterprise Grid org installs require stable Slack channel IDs with workspace scope; invalid channels key ${JSON.stringify(channelKey)}`, ); } assertStableEntries({ values: channel?.users, path: `channels.slack.accounts.${accountId}.channels.${channelKey}.users`, - predicate: isStableSlackAllowlistUserEntry, + predicate: isWorkspaceScopedSlackAllowlistUserEntry, }); assertStableEntries({ values: Object.keys(channel?.toolsBySender ?? {}), diff --git a/extensions/slack/src/monitor/events/channels.ts b/extensions/slack/src/monitor/events/channels.ts index 009f9661b021..c6fce1b4a16a 100644 --- a/extensions/slack/src/monitor/events/channels.ts +++ b/extensions/slack/src/monitor/events/channels.ts @@ -35,6 +35,7 @@ export function registerSlackChannelEvents(params: { }) => { if ( !ctx.isChannelAllowed({ + teamId: paramsLocal.eventScope?.teamId ?? ctx.teamId, channelId: paramsLocal.channelId, channelName: paramsLocal.channelName, channelType: "channel", diff --git a/extensions/slack/src/monitor/events/interactions.block-actions.ts b/extensions/slack/src/monitor/events/interactions.block-actions.ts index 745d69501aef..aa861381ab1f 100644 --- a/extensions/slack/src/monitor/events/interactions.block-actions.ts +++ b/extensions/slack/src/monitor/events/interactions.block-actions.ts @@ -914,6 +914,8 @@ async function resolveSlackBlockActionCommandAuthorized(params: { let channelUsers: Array = []; if (isRoom && params.parsed.channelId) { const channelConfig = resolveSlackChannelConfig({ + teamId: params.eventScope?.teamId ?? params.ctx.teamId, + allowUnscoped: params.ctx.installationIdentity?.kind !== "enterprise", channelId: params.parsed.channelId, channelName: params.auth.channelName, channels: params.ctx.channelsConfig, @@ -926,6 +928,7 @@ async function resolveSlackBlockActionCommandAuthorized(params: { const commandIngress = await resolveSlackCommandIngress({ ctx: params.ctx, + teamId: params.eventScope?.teamId ?? params.ctx.teamId, senderId: params.parsed.userId, senderName, channelType: params.auth.channelType ?? "channel", diff --git a/extensions/slack/src/monitor/events/reactions.ts b/extensions/slack/src/monitor/events/reactions.ts index f2efc8a78a37..70ca13acdc4e 100644 --- a/extensions/slack/src/monitor/events/reactions.ts +++ b/extensions/slack/src/monitor/events/reactions.ts @@ -15,6 +15,7 @@ import { function shouldEmitSlackReactionNotification(params: { ctx: SlackMonitorContext; event: SlackReactionEvent; + eventScope?: SlackEventScope; actorName?: string; }) { const { ctx, event, actorName } = params; @@ -31,9 +32,11 @@ function shouldEmitSlackReactionNotification(params: { } return allowListMatches({ allowList, + teamId: params.eventScope?.teamId ?? ctx.teamId, id: event.user, name: actorName, allowNameMatching: ctx.allowNameMatching, + allowUnscoped: ctx.installationIdentity?.kind !== "enterprise", }); } return ctx.reactionMode === "all"; @@ -88,6 +91,7 @@ export function registerSlackReactionEvents(params: { !shouldEmitSlackReactionNotification({ ctx, event, + eventScope, actorName: actorInfo?.name, }) ) { diff --git a/extensions/slack/src/monitor/message-handler/prepare.test.ts b/extensions/slack/src/monitor/message-handler/prepare.test.ts index 1b0ded3dac00..23090bf00bcf 100644 --- a/extensions/slack/src/monitor/message-handler/prepare.test.ts +++ b/extensions/slack/src/monitor/message-handler/prepare.test.ts @@ -574,6 +574,58 @@ describe("slack prepareSlackMessage inbound contract", () => { }); }); + it("applies workspace-qualified channel users during message ingress", async () => { + const channelsConfig = { + "team:T123ENTERPRISE:channel:C123CHANNEL": { + enabled: true, + requireMention: false, + users: ["team:T123ENTERPRISE:user:U123"], + }, + "team:T456ENTERPRISE:channel:C123CHANNEL": { + enabled: true, + requireMention: false, + users: ["team:T456ENTERPRISE:user:U456"], + }, + }; + const ctx = createInboundSlackCtx({ + cfg: { channels: { slack: { enabled: true, groupPolicy: "allowlist" } } }, + channelsConfig, + defaultRequireMention: false, + groupPolicy: "allowlist", + }); + ctx.resolveChannelName = async () => ({ name: "general", type: "channel" }); + ctx.resolveUserName = async () => ({ name: "Alice" }); + const account = createSlackAccount({ groupPolicy: "allowlist", channels: channelsConfig }); + const message = createSlackMessage({ + channel: "C123CHANNEL", + channel_type: "channel", + user: "U123", + text: "hello", + }); + + const allowed = await prepareSlackMessage({ + ctx, + account, + message, + opts: { + source: "message", + eventScope: { teamId: "T123ENTERPRISE", client: ctx.app.client }, + }, + }); + const blocked = await prepareSlackMessage({ + ctx, + account, + message, + opts: { + source: "message", + eventScope: { teamId: "T456ENTERPRISE", client: ctx.app.client }, + }, + }); + + assertPrepared(allowed, "workspace-qualified channel user"); + expect(blocked).toBeNull(); + }); + it("applies workspace-qualified Enterprise mention pattern policy", async () => { const cfg = { messages: { groupChat: { mentionPatterns: ["\\bbill\\b"] } }, diff --git a/extensions/slack/src/monitor/message-handler/prepare.ts b/extensions/slack/src/monitor/message-handler/prepare.ts index 90c0fb976409..e447ee8a34e4 100644 --- a/extensions/slack/src/monitor/message-handler/prepare.ts +++ b/extensions/slack/src/monitor/message-handler/prepare.ts @@ -538,6 +538,8 @@ async function resolveSlackConversationContext(params: { const isRoomish = isRoom || isGroupDm; const channelConfig = isRoom ? resolveSlackChannelConfig({ + teamId: params.eventScope?.teamId ?? ctx.teamId, + allowUnscoped: ctx.installationIdentity?.kind !== "enterprise", channelId: message.channel, channelName, channels: ctx.channelsConfig, @@ -604,6 +606,7 @@ async function authorizeSlackInboundMessage(params: { if ( !ctx.isChannelAllowed({ + teamId: params.eventScope?.teamId ?? ctx.teamId, channelId: message.channel, channelName, channelType: resolvedChannelType, @@ -1136,6 +1139,7 @@ export async function prepareSlackMessage(params: { isRoom && Array.isArray(channelConfig?.users) && channelConfig.users.length > 0; const messageIngress = await resolveSlackCommandIngress({ ctx, + teamId: opts.eventScope?.teamId ?? ctx.teamId, senderId, senderName: senderNameForAuth, channelType: conversation.resolvedChannelType ?? "channel", @@ -1771,7 +1775,7 @@ export async function prepareSlackMessage(params: { const pinnedMainDmOwner = isDirectMessage ? resolvePinnedMainDmOwnerFromAllowlist({ dmScope: cfg.session?.dmScope, - allowFrom: ctx.allowFrom, + allowFrom: allowFromLower, normalizeEntry: normalizeSlackAllowOwnerEntry, }) : null; diff --git a/extensions/slack/src/monitor/monitor.test.ts b/extensions/slack/src/monitor/monitor.test.ts index 9d0cd1b38cc5..dd58881401e1 100644 --- a/extensions/slack/src/monitor/monitor.test.ts +++ b/extensions/slack/src/monitor/monitor.test.ts @@ -162,6 +162,93 @@ describe("resolveSlackChannelConfig", () => { }); }); + it("prefers a workspace-qualified channel over the same channel ID in another workspace", () => { + const channels = { + "team:T11111111:channel:C01234567": { enabled: true, requireMention: false }, + "team:T22222222:channel:C01234567": { enabled: false, requireMention: true }, + }; + + expectSlackChannelConfig( + resolveSlackChannelConfig({ + teamId: "T11111111", + channelId: "C01234567", + channels, + }), + { + allowed: true, + requireMention: false, + matchKey: "team:T11111111:channel:C01234567", + matchSource: "direct", + }, + ); + expectSlackChannelConfig( + resolveSlackChannelConfig({ + teamId: "T22222222", + channelId: "C01234567", + channels, + }), + { + allowed: false, + requireMention: true, + matchKey: "team:T22222222:channel:C01234567", + matchSource: "direct", + }, + ); + }); + + it("does not match a bare channel ID when workspace scope is required", () => { + const channels = { C01234567: { enabled: true, requireMention: false } }; + + expectSlackChannelConfig( + resolveSlackChannelConfig({ + teamId: "T11111111", + channelId: "C01234567", + channels, + }), + { allowed: false, requireMention: true }, + ); + expectSlackChannelConfig( + resolveSlackChannelConfig({ + teamId: "T11111111", + allowUnscoped: true, + channelId: "C01234567", + channels, + }), + { + allowed: true, + requireMention: false, + matchKey: "C01234567", + matchSource: "direct", + }, + ); + }); + + it("matches per-channel users only in their selected workspace", () => { + const channels = { + "team:T11111111:channel:C01234567": { + users: ["team:T11111111:user:U01234567", "team:T22222222:user:U12345678", "U23456789"], + }, + "team:T22222222:channel:C01234567": { + users: ["team:T11111111:user:U01234567", "team:T22222222:user:U12345678", "U23456789"], + }, + }; + + expect( + resolveSlackChannelConfig({ + teamId: "T11111111", + channelId: "C01234567", + channels, + })?.users, + ).toEqual(["team:t11111111:user:u01234567", "team:t22222222:user:u12345678", "u23456789"]); + expect( + resolveSlackChannelConfig({ + teamId: "T22222222", + channelId: "C01234567", + channels, + })?.users, + ).toEqual(["team:t11111111:user:u01234567", "team:t22222222:user:u12345678", "u23456789"]); + }); + it("blocks channel-name route matches by default", () => { const res = resolveSlackChannelConfig({ channelId: "C1", diff --git a/extensions/slack/src/monitor/slash.ts b/extensions/slack/src/monitor/slash.ts index 49bd3572018b..0618104c811b 100644 --- a/extensions/slack/src/monitor/slash.ts +++ b/extensions/slack/src/monitor/slash.ts @@ -498,6 +498,7 @@ export async function registerSlackMonitorSlashCommands(params: { if ( !ctx.isChannelAllowed({ + teamId: eventScope?.teamId ?? ctx.teamId, channelId: command.channel_id, channelName: channelInfo?.name, channelType, @@ -557,6 +558,8 @@ export async function registerSlackMonitorSlashCommands(params: { if (isRoom) { channelConfig = resolveSlackChannelConfig({ + teamId: eventScope?.teamId ?? ctx.teamId, + allowUnscoped: ctx.installationIdentity?.kind !== "enterprise", channelId: command.channel_id, channelName: channelInfo?.name, channels: ctx.channelsConfig, @@ -598,6 +601,7 @@ export async function registerSlackMonitorSlashCommands(params: { const senderName = sender?.name ?? command.user_name ?? command.user_id; const slashIngress = await resolveSlackCommandIngress({ ctx, + teamId: eventScope?.teamId ?? ctx.teamId, senderId: command.user_id, senderName, channelType: channelType ?? "channel", diff --git a/extensions/slack/src/resolve-channels.test.ts b/extensions/slack/src/resolve-channels.test.ts index 132b2054323b..b9d9157393f9 100644 --- a/extensions/slack/src/resolve-channels.test.ts +++ b/extensions/slack/src/resolve-channels.test.ts @@ -45,6 +45,21 @@ describe("resolveSlackChannelAllowlist", () => { expect(list).not.toHaveBeenCalled(); }); + it("preserves workspace-qualified channel ids without listing a workspace", async () => { + const list = vi.fn(); + const res = await resolveSlackChannelAllowlist({ + token: "xoxb-test", + entries: ["team:T11111111:channel:C01234567", "team:T22222222:channel:C01234567"], + client: { conversations: { list } } as never, + }); + + expect(res.map((entry) => entry.id)).toEqual([ + "team:T11111111:channel:C01234567", + "team:T22222222:channel:C01234567", + ]); + expect(list).not.toHaveBeenCalled(); + }); + it("resolves by name and prefers active channels", async () => { const client = { conversations: { diff --git a/extensions/slack/src/resolve-channels.ts b/extensions/slack/src/resolve-channels.ts index f66f45363c73..cee5cc0b5a5d 100644 --- a/extensions/slack/src/resolve-channels.ts +++ b/extensions/slack/src/resolve-channels.ts @@ -4,6 +4,7 @@ import { resolveDirectoryAllowlistEntries } from "openclaw/plugin-sdk/directory- import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime"; import { createSlackLookupClient } from "./client.js"; import { collectSlackCursorPages } from "./cursor-pages.js"; +import { formatSlackTarget, parseSlackTarget } from "./target-parsing.js"; export type SlackChannelLookup = { id: string; @@ -20,6 +21,25 @@ export type SlackChannelResolution = { archived?: boolean; }; +function resolveWorkspaceQualifiedChannel(input: string): SlackChannelResolution | undefined { + if (!/^team:/i.test(input)) { + return undefined; + } + try { + const target = parseSlackTarget(input); + if (target?.kind !== "channel" || !target.teamId) { + return undefined; + } + return { + input, + resolved: true, + id: formatSlackTarget({ teamId: target.teamId, kind: "channel", id: target.id }), + }; + } catch { + return undefined; + } +} + function parseSlackChannelMention(raw: string): { id?: string; name?: string } { const trimmed = raw.trim(); if (!trimmed) { @@ -90,26 +110,35 @@ export async function resolveSlackChannelAllowlist(params: { entries: string[]; client?: WebClient; }): Promise { - const parsedEntries = params.entries.map((input) => ({ + const workspaceResolved = params.entries.map(resolveWorkspaceQualifiedChannel); + const lookupEntries = params.entries.filter((_, index) => !workspaceResolved[index]); + if (lookupEntries.length === 0) { + return workspaceResolved.filter( + (entry): entry is SlackChannelResolution => entry !== undefined, + ); + } + const parsedEntries = lookupEntries.map((input) => ({ input, parsed: parseSlackChannelMention(input), })); if (parsedEntries.every((entry) => Boolean(entry.parsed.id))) { - return parsedEntries.map(({ input, parsed }) => ({ + const resolved = parsedEntries.map(({ input, parsed }) => ({ input, resolved: true, id: parsed.id, name: parsed.name, })); + let resolvedIndex = 0; + return workspaceResolved.map((entry) => entry ?? resolved[resolvedIndex++]!); } const client = params.client ?? createSlackLookupClient(params.token); const channels = await listSlackChannels(client); - return resolveDirectoryAllowlistEntries< + const resolved = resolveDirectoryAllowlistEntries< { id?: string; name?: string }, SlackChannelLookup, SlackChannelResolution >({ - entries: params.entries, + entries: lookupEntries, lookup: channels, parseInput: parseSlackChannelMention, findById: (lookup, id) => lookup.find((channel) => channel.id === id), @@ -138,4 +167,6 @@ export async function resolveSlackChannelAllowlist(params: { }, buildUnresolved: (input) => ({ input, resolved: false }), }); + let resolvedIndex = 0; + return workspaceResolved.map((entry) => entry ?? resolved[resolvedIndex++]!); } diff --git a/extensions/slack/src/resolve-users.test.ts b/extensions/slack/src/resolve-users.test.ts index d3b3a5cd2d13..9d5c5c1f53c4 100644 --- a/extensions/slack/src/resolve-users.test.ts +++ b/extensions/slack/src/resolve-users.test.ts @@ -75,6 +75,21 @@ describe("resolveSlackUserAllowlist", () => { }); }); + it("preserves workspace-qualified user ids without listing a workspace", async () => { + const list = vi.fn(); + const res = await resolveSlackUserAllowlist({ + token: "xoxb-test", + entries: ["team:T11111111:user:U01234567", "team:T22222222:user:U01234567"], + client: { users: { list } } as never, + }); + + expect(res.map((entry) => entry.id)).toEqual([ + "team:T11111111:user:U01234567", + "team:T22222222:user:U01234567", + ]); + expect(list).not.toHaveBeenCalled(); + }); + it("keeps unresolved users", async () => { const client = { users: { diff --git a/extensions/slack/src/resolve-users.ts b/extensions/slack/src/resolve-users.ts index 4c97a76914ec..01b52ad2856b 100644 --- a/extensions/slack/src/resolve-users.ts +++ b/extensions/slack/src/resolve-users.ts @@ -7,6 +7,7 @@ import { } from "openclaw/plugin-sdk/string-coerce-runtime"; import { createSlackLookupClient } from "./client.js"; import { collectSlackCursorPages } from "./cursor-pages.js"; +import { formatSlackTarget, parseSlackTarget } from "./target-parsing.js"; export type SlackUserLookup = { id: string; @@ -30,6 +31,25 @@ export type SlackUserResolution = { note?: string; }; +function resolveWorkspaceQualifiedUser(input: string): SlackUserResolution | undefined { + if (!/^team:/i.test(input)) { + return undefined; + } + try { + const target = parseSlackTarget(input); + if (target?.kind !== "user" || !target.teamId) { + return undefined; + } + return { + input, + resolved: true, + id: formatSlackTarget({ teamId: target.teamId, kind: "user", id: target.id }), + }; + } catch { + return undefined; + } +} + function parseSlackUserInput(raw: string): { id?: string; name?: string; email?: string } { const trimmed = raw.trim(); if (!trimmed) { @@ -138,14 +158,19 @@ export async function resolveSlackUserAllowlist(params: { entries: string[]; client?: WebClient; }): Promise { + const workspaceResolved = params.entries.map(resolveWorkspaceQualifiedUser); + const lookupEntries = params.entries.filter((_, index) => !workspaceResolved[index]); + if (lookupEntries.length === 0) { + return workspaceResolved.filter((entry): entry is SlackUserResolution => entry !== undefined); + } const client = params.client ?? createSlackLookupClient(params.token); const users = await listSlackUsers(client); - return resolveDirectoryAllowlistEntries< + const resolved = resolveDirectoryAllowlistEntries< { id?: string; name?: string; email?: string }, SlackUserLookup, SlackUserResolution >({ - entries: params.entries, + entries: lookupEntries, lookup: users, parseInput: parseSlackUserInput, findById: (lookup, id) => lookup.find((user) => user.id === id), @@ -181,4 +206,6 @@ export async function resolveSlackUserAllowlist(params: { }, buildUnresolved: (input) => ({ input, resolved: false }), }); + let resolvedIndex = 0; + return workspaceResolved.map((entry) => entry ?? resolved[resolvedIndex++]!); } diff --git a/extensions/slack/src/security-doctor.ts b/extensions/slack/src/security-doctor.ts index 28398cf40cb4..85d21c614b82 100644 --- a/extensions/slack/src/security-doctor.ts +++ b/extensions/slack/src/security-doctor.ts @@ -1,7 +1,22 @@ // Slack plugin module implements security doctor behavior. import { buildMutableAllowEntryDetector } from "openclaw/plugin-sdk/channel-policy"; +import { parseSlackTarget } from "./target-parsing.js"; -export const isSlackMutableAllowEntry = buildMutableAllowEntryDetector({ +const isSlackMutableUnqualifiedAllowEntry = buildMutableAllowEntryDetector({ stableIdPattern: /^(?:(?:(?:[sS][lL][aA][cC][kK]|[uU][sS][eE][rR]):)?(?:[UWBCGDT][A-Z0-9]{2,}|[A-Za-z0-9]{8,})|<@[A-Za-z0-9]{8,}>)$/, }); + +export function isSlackMutableAllowEntry(entry: string): boolean { + if (/^team:/i.test(entry)) { + try { + const target = parseSlackTarget(entry); + if (target?.kind === "user" && target.teamId) { + return false; + } + } catch { + // Invalid qualified entries remain mutable so Doctor reports them. + } + } + return isSlackMutableUnqualifiedAllowEntry(entry); +} diff --git a/extensions/slack/src/target-parsing.ts b/extensions/slack/src/target-parsing.ts index 73b6415d7a9f..f8caaef9ba83 100644 --- a/extensions/slack/src/target-parsing.ts +++ b/extensions/slack/src/target-parsing.ts @@ -20,7 +20,7 @@ export type SlackTargetParseOptions = MessagingTargetParseOptions; // Letter-leading folded IDs are indistinguishable from supported channel names. // Doctor reports that ambiguity; runtime repairs only the digit-leading form. const SLACK_CHANNEL_API_ID_RE = /^[CDG][0-9][A-Z0-9]{7,}$/i; -const SLACK_USER_API_ID_RE = /^[UW][A-Z0-9]{8,}$/i; +const SLACK_USER_API_ID_RE = /^[BUW][A-Z0-9]{8,}$/i; const SLACK_QUALIFIED_TARGET_RE = /^team:([^:]+):(user|channel):([^:]+)$/i; function decodeSlackTargetPart(raw: string): string | undefined { @@ -44,7 +44,7 @@ function parseQualifiedSlackTarget(raw: string): SlackTarget | undefined { const teamId = decodeSlackTargetPart(match[1] ?? ""); const kind = match[2]?.toLowerCase() as SlackTargetKind | undefined; const id = decodeSlackTargetPart(match[3] ?? ""); - const idPattern = kind === "user" ? /^[UW][A-Z0-9]+$/i : /^[CDG][A-Z0-9]+$/i; + const idPattern = kind === "user" ? /^[BUW][A-Z0-9]+$/i : /^[CDG][A-Z0-9]+$/i; if (!teamId || !/^T[A-Z0-9]+$/i.test(teamId) || !kind || !id || !idPattern.test(id)) { throw new Error("Invalid Slack workspace-qualified target"); } @@ -68,7 +68,7 @@ export function formatSlackTarget(params: { if (!teamId) { return params.explicitKind ? `${params.kind}:${id}` : id; } - const idPattern = params.kind === "user" ? /^[UW][A-Z0-9]+$/i : /^[CDG][A-Z0-9]+$/i; + const idPattern = params.kind === "user" ? /^[BUW][A-Z0-9]+$/i : /^[CDG][A-Z0-9]+$/i; if (!/^T[A-Z0-9]+$/i.test(teamId) || !idPattern.test(id)) { throw new Error("Invalid Slack workspace-qualified target"); } diff --git a/extensions/slack/src/targets.test.ts b/extensions/slack/src/targets.test.ts index 50d269b2114a..e2a8676fafc4 100644 --- a/extensions/slack/src/targets.test.ts +++ b/extensions/slack/src/targets.test.ts @@ -65,6 +65,13 @@ describe("parseSlackTarget", () => { raw: "team:T789:user:U012", normalized: "team:t789:user:u012", }); + expect(parseSlackTarget("team:T789:user:B345")).toEqual({ + kind: "user", + id: "B345", + teamId: "T789", + raw: "team:T789:user:B345", + normalized: "team:t789:user:b345", + }); }); it("formats bare and structurally valid workspace-qualified targets", () => { @@ -72,6 +79,9 @@ describe("parseSlackTarget", () => { "team:T123:channel:C456", ); expect(formatSlackTarget({ kind: "channel", id: "C456" })).toBe("C456"); + expect(formatSlackTarget({ teamId: "T123", kind: "user", id: "B456" })).toBe( + "team:T123:user:B456", + ); expect(() => formatSlackTarget({ teamId: "E123", kind: "channel", id: "C456" })).toThrow( "Invalid Slack workspace-qualified target", ); From 61ab6a8f9d151c84377ba9f90152f257110cc5a6 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 22:12:53 -0700 Subject: [PATCH 024/165] feat(gateway): make suspend/resume operator-usable end to end (#122100) * feat(gateway): make suspend/resume operator-usable end to end A prepared Gateway now accepts authenticated WebSocket connects while keeping every method except gateway.suspend.* fenced, so a fresh CLI or controller process can resume a suspension instead of dead-ending on a rejected upgrade until the two-minute lease expires. Restart drain, worker ingress, and desktop-observe streams stay fully closed. The gateway client surfaces non-101 upgrade responses (bounded body read) as typed retryable errors instead of an opaque 1006 close, and new openclaw gateway suspend / resume commands drive the whole handshake, including bounded --wait polling with blocker output. Live-verified on an isolated dev gateway: prepare, SIGSTOP/SIGCONT freeze, resume, over-TTL expiry self-heal, conflict and mismatch paths. * refactor(gateway-client): move wire-client contract types to protocol-client-contract The connectError addition pushed protocol-client.ts over the 700-line max-lines gate; split the adapter-facing contract types into their own module instead of suppressing. * refactor(gateway-client): keep contract-internal option types unexported Knip deadcode gates reject exported types with no importer; the connect and close decision shapes are only referenced inside the contract module. * chore(plugin-sdk): refresh gateway-runtime API baseline after rebase * fix(gateway-client): preserve hello type after rebase * test(gateway): support websocket upgrade rejection events * test(gateway): expect connection errors in close info * fix(gateway): keep prepared-suspension connects control-only Address ClawSweeper review: node and worker connects stay refused while suspension is prepared (only operator control connects pass), and the CLI never issues another suspend prepare after its --wait deadline. --- .../gateway-runtime.json | 2 +- docs/cli/gateway.md | 30 ++++ docs/gateway/external-apps.md | 16 +- docs/gateway/protocol.md | 2 +- .../src/client.handshake.test.ts | 109 ++++++++++- packages/gateway-client/src/client.ts | 69 +++++++ .../src/protocol-client-contract.ts | 114 ++++++++++++ .../gateway-client/src/protocol-client.ts | 127 ++----------- .../register.option-collisions.test.ts | 44 ++++- src/cli/gateway-cli/register.ts | 49 +++++ src/cli/gateway-cli/suspend-cli.test.ts | 169 ++++++++++++++++++ src/cli/gateway-cli/suspend-cli.ts | 157 ++++++++++++++++ src/gateway/call.test.ts | 28 +++ src/gateway/call.ts | 5 + src/gateway/client.test.ts | 6 + src/gateway/probe.device-auth-scope.test.ts | 3 +- src/gateway/server-http.ts | 16 +- src/gateway/server.preauth-hardening.test.ts | 75 +++++++- ...ssage-handler.suspension-admission.test.ts | 162 ++++++++++++----- .../server/ws-connection/message-handler.ts | 35 +++- 20 files changed, 1034 insertions(+), 184 deletions(-) create mode 100644 packages/gateway-client/src/protocol-client-contract.ts create mode 100644 src/cli/gateway-cli/suspend-cli.test.ts create mode 100644 src/cli/gateway-cli/suspend-cli.ts diff --git a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json index 296271a135ae..1751f4ed359a 100644 --- a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json @@ -1 +1 @@ -{"contentHash":"85a649a9621f78be5d7e26b01ec4b8d465f7c353109571be30530b5c8c4bd5ac","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} +{"contentHash":"e31574637f3e276338e3e05e4774f7ad79981042c8021e49fb53df7ffe901917","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index 046cb63cc8d0..6f0555978526 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -516,6 +516,36 @@ openclaw gateway call logs.tail --params '{"limit": 200}' `--params` must be valid JSON, and each method validates its own param shape (extra/misnamed fields are rejected). Use `--port` for a custom-port local Gateway; explicit `--url` targets still require explicit credentials. +### `gateway suspend` + +Prepare an idle Gateway for a cooperative host freeze or snapshot. Without +`--wait`, active work returns a nonzero exit with blocker details. With +`--wait`, the CLI retries until the bounded deadline using one stable request +ID. + +```bash +openclaw gateway suspend +openclaw gateway suspend --request-id snapshot-2026-08-11 --wait 30 +openclaw gateway suspend --port 18999 --json +``` + +The ready output includes the suspension ID, lease expiry, and the matching +resume command. Common RPC options such as `--url`, `--token`, `--password`, +`--timeout`, `--json`, and `--port` are supported. + +### `gateway resume ` + +Release a prepared suspension after thaw or when the host operation is +abandoned. + +```bash +openclaw gateway resume +openclaw gateway resume --port 18999 --json +``` + +An already expired or resumed lease is a successful no-op. A different active +suspension ID is rejected. + ## Manage the Gateway service ```bash diff --git a/docs/gateway/external-apps.md b/docs/gateway/external-apps.md index 9edae0d38813..4d7b4c2ca873 100644 --- a/docs/gateway/external-apps.md +++ b/docs/gateway/external-apps.md @@ -64,15 +64,15 @@ host-neutral suspension handshake: 4. If it is `ready`, save the returned `suspensionId`, then freeze or snapshot the process before `expiresAtMs`. 5. After thaw, or if suspension is abandoned, call `gateway.suspend.resume` - with that `suspensionId` over the existing WebSocket or Admin HTTP control - path. + with that `suspensionId` over the existing or a newly authenticated + WebSocket. The CLI equivalents are `openclaw gateway suspend` and + `openclaw gateway resume `. -A prepared Gateway rejects new WebSocket handshakes. A WebSocket controller -must keep its authenticated connection open across the host operation. If that -cannot be guaranteed, enable and use the -[Admin HTTP RPC plugin](/plugins/admin-http-rpc) before preparing. If the -control path is lost, wait for the two-minute lease to expire before -reconnecting; expiry reopens admission automatically. +A prepared Gateway accepts authenticated WebSocket connects, but fences every +method except `gateway.suspend.*`. Controllers may reconnect after thaw and +call resume. The [Admin HTTP RPC plugin](/plugins/admin-http-rpc) remains +available for hosts that cannot speak WebSocket at all. If every control path +is lost, the two-minute lease expiry reopens admission automatically. The RPC contract is: diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 0323ed32660d..f52522db80d9 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -520,7 +520,7 @@ methods. Treat this as feature discovery, not a full enumeration of - `last-heartbeat` returns the latest persisted heartbeat event. - `set-heartbeats` toggles heartbeat processing on the gateway. - `gateway.restart.preflight` is a deprecated, read-only compatibility preview of restart-specific active work. It does not close admission, create a suspension lease, or provide the atomic full-work fence of `gateway.suspend.prepare`; new restart flows should call `gateway.restart.request`. - - `gateway.suspend.prepare` creates a short cooperative-suspension lease only when tracked Gateway work is idle. `gateway.suspend.status` checks that lease, and `gateway.suspend.resume` releases it after thaw or an aborted host operation. + - `gateway.suspend.prepare` creates a short cooperative-suspension lease only when tracked Gateway work is idle. While prepared, authenticated WebSocket connects remain available, but every method except `gateway.suspend.*` is fenced. `gateway.suspend.status` checks the lease, and `gateway.suspend.resume` releases it after thaw or an aborted host operation. diff --git a/packages/gateway-client/src/client.handshake.test.ts b/packages/gateway-client/src/client.handshake.test.ts index e5eb3f60a2cb..23f93891f7e1 100644 --- a/packages/gateway-client/src/client.handshake.test.ts +++ b/packages/gateway-client/src/client.handshake.test.ts @@ -1,4 +1,5 @@ // Gateway Client tests cover websocket opening-handshake timeout behavior. +import http from "node:http"; import net from "node:net"; import type { AddressInfo } from "node:net"; import { afterEach, describe, expect, it } from "vitest"; @@ -16,6 +17,9 @@ describe("GatewayClient websocket opening handshakeTimeout", () => { for (const socket of sockets.splice(0)) { socket.destroy(); } + for (const server of servers) { + (server as net.Server & { closeAllConnections?: () => void }).closeAllConnections?.(); + } await Promise.all( servers.splice(0).map( (server) => @@ -26,18 +30,22 @@ describe("GatewayClient websocket opening handshakeTimeout", () => { ); }); + async function listen(server: net.Server): Promise { + servers.push(server); + await new Promise((resolve, reject) => { + server.once("error", reject); + server.listen(0, "127.0.0.1", () => resolve()); + }); + return (server.address() as AddressInfo).port; + } + it("fails when a peer accepts TCP but never completes the websocket upgrade", async () => { // Accept TCP but never complete the websocket upgrade so missing // handshakeTimeout would leave start() waiting forever for open. const server = net.createServer((socket) => { sockets.push(socket); }); - servers.push(server); - await new Promise((resolve, reject) => { - server.once("error", reject); - server.listen(0, "127.0.0.1", () => resolve()); - }); - const { port } = server.address() as AddressInfo; + const port = await listen(server); const handshakeTimeoutMs = 250; const startedAt = Date.now(); const outcome = await new Promise<{ @@ -89,4 +97,93 @@ describe("GatewayClient websocket opening handshakeTimeout", () => { }`, ); }); + + it("surfaces a rejected websocket upgrade body through the connection error", async () => { + let requestCount = 0; + const server = http.createServer((_req, res) => { + requestCount += 1; + res.writeHead(503, { "Content-Type": "text/plain" }); + res.end("Gateway websocket admission closed"); + }); + const port = await listen(server); + const errors: Error[] = []; + let resolveRetry = () => {}; + const retried = new Promise((resolve) => { + resolveRetry = resolve; + }); + const closed = new Promise<{ code: number; connectError?: Error }>((resolve) => { + const client = new GatewayClient({ + url: `ws://127.0.0.1:${port}`, + onConnectError: (error) => { + errors.push(error); + if (errors.length === 2) { + resolveRetry(); + } + }, + onClose: (code, _reason, info) => resolve({ code, connectError: info?.connectError }), + }); + clients.push(client); + client.start(); + }); + + await expect(closed).resolves.toMatchObject({ + code: 1006, + connectError: { + name: "GatewayClientRequestError", + message: + "gateway rejected websocket upgrade (HTTP 503): Gateway websocket admission closed", + gatewayCode: "UNAVAILABLE", + retryable: true, + }, + }); + await retried; + expect(requestCount).toBe(2); + expect(errors).toHaveLength(2); + expect(errors.map((error) => error.message)).toEqual([ + "gateway rejected websocket upgrade (HTTP 503): Gateway websocket admission closed", + "gateway rejected websocket upgrade (HTTP 503): Gateway websocket admission closed", + ]); + }); + + it("caps a rejected websocket upgrade body before the peer ends it", async () => { + const omittedTail = "omitted-tail-marker"; + const server = http.createServer((_req, res) => { + res.writeHead(503, { "Content-Type": "text/plain" }); + res.write(`${"x".repeat(3_000)}${omittedTail}`); + }); + const port = await listen(server); + const error = await new Promise((resolve) => { + const client = new GatewayClient({ + url: `ws://127.0.0.1:${port}`, + onConnectError: resolve, + }); + clients.push(client); + client.start(); + }); + + expect(error.message).toHaveLength( + "gateway rejected websocket upgrade (HTTP 503): ".length + 2 * 1024, + ); + expect(error.message).not.toContain(omittedTail); + }); + + it("times out while reading a stalled websocket upgrade response body", async () => { + const server = http.createServer((_req, res) => { + res.writeHead(503, { "Content-Type": "text/plain" }); + res.write("still suspending"); + }); + const port = await listen(server); + const startedAt = Date.now(); + const error = await new Promise((resolve) => { + const client = new GatewayClient({ + url: `ws://127.0.0.1:${port}`, + onConnectError: resolve, + }); + clients.push(client); + client.start(); + }); + + expect(error.message).toBe("gateway rejected websocket upgrade (HTTP 503): still suspending"); + expect(Date.now() - startedAt).toBeLessThan(1_500); + }); }); diff --git a/packages/gateway-client/src/client.ts b/packages/gateway-client/src/client.ts index d1799a4d763c..7b376c995730 100644 --- a/packages/gateway-client/src/client.ts +++ b/packages/gateway-client/src/client.ts @@ -1,4 +1,5 @@ import { randomUUID } from "node:crypto"; +import type { ClientRequest, IncomingMessage } from "node:http"; import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, @@ -229,6 +230,50 @@ type FingerprintCheckingClientOptions = Omit { + return await new Promise((resolve) => { + const chunks: Buffer[] = []; + let totalBytes = 0; + let settled = false; + const finish = () => { + if (settled) { + return; + } + settled = true; + clearTimeout(timer); + response.off("data", onData); + response.off("end", finish); + response.off("error", finish); + response.off("aborted", finish); + resolve(Buffer.concat(chunks, totalBytes).toString("utf8").replace(/\s+/gu, " ").trim()); + }; + const stop = () => { + finish(); + response.destroy(); + }; + const onData = (chunk: Buffer | string) => { + const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); + const remaining = MAX_UPGRADE_ERROR_BODY_BYTES - totalBytes; + if (remaining > 0) { + const prefix = buffer.subarray(0, remaining); + chunks.push(prefix); + totalBytes += prefix.byteLength; + } + if (buffer.byteLength >= remaining) { + stop(); + } + }; + const timer = setTimeout(stop, UPGRADE_ERROR_BODY_TIMEOUT_MS); + timer.unref?.(); + response.on("data", onData); + response.once("end", finish); + response.once("error", finish); + response.once("aborted", finish); + }); +} export type GatewayReconnectPausedInfo = { code: number; @@ -241,6 +286,7 @@ export type GatewayClientCloseInfo = { socketOpened: boolean; transportValidated: boolean; transientPreHelloCleanClose: boolean; + connectError?: Error; }; export { GatewayClientRequestError } from "./request-error.js"; @@ -608,6 +654,7 @@ export class GatewayClient { } this.ws = ws; this.transportValidated = false; + let upgradeError: GatewayClientRequestError | undefined; ws.on("open", () => { handlers.open(); if (usesTls && this.opts.tlsFingerprint) { @@ -629,7 +676,28 @@ export class GatewayClient { this.resolvePendingStop(ws); handlers.close(code, reasonText); }); + ws.on("unexpected-response", (request: ClientRequest, response: IncomingMessage) => { + void readUpgradeErrorBody(response).then((body) => { + const statusCode = response.statusCode; + const message = `gateway rejected websocket upgrade (HTTP ${statusCode ?? "unknown"})${body ? `: ${body}` : ""}`; + upgradeError = new GatewayClientRequestError({ + code: "UNAVAILABLE", + message, + retryable: true, + details: { + reason: "websocket-upgrade-rejected", + ...(statusCode === undefined ? {} : { httpStatus: statusCode }), + }, + }); + handlers.error(upgradeError); + request.destroy(); + ws.close(); + }); + }); ws.on("error", (err) => { + if (upgradeError) { + return; + } this.logDebug(`gateway client error: ${formatGatewayClientErrorForLog(err)}`); handlers.error(err instanceof Error ? err : new Error(String(err))); }); @@ -1153,6 +1221,7 @@ export class GatewayClient { transportValidated: this.transportValidated, transientPreHelloCleanClose: !context.helloReceived && context.code === 1000 && context.reason === "", + ...(context.connectFailure?.error ? { connectError: context.connectFailure.error } : {}), }; } diff --git a/packages/gateway-client/src/protocol-client-contract.ts b/packages/gateway-client/src/protocol-client-contract.ts new file mode 100644 index 000000000000..52535b300137 --- /dev/null +++ b/packages/gateway-client/src/protocol-client-contract.ts @@ -0,0 +1,114 @@ +// Wire-client contract types shared by GatewayProtocolClient and its adapters. +import type { ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol"; +import type { GatewayProtocolRequestTiming } from "./pending-request.js"; +import type { GatewayProtocolRequestError } from "./protocol-request.js"; + +export type GatewayProtocolSocket = { + isOpen: () => boolean; + send: (data: string) => void; + close: (code?: number, reason?: string) => void; +}; +export type GatewayProtocolSocketHandlers = { + open: () => void; + message: (data: string) => void; + close: (code: number, reason: string) => void; + error: (error: Error) => void; +}; +type GatewayProtocolConnectContext = { + generation: number; + nonce: string | null; + challengeTs: number | null | undefined; + plan: TPlan; +}; +export type GatewayProtocolCloseContext = { + code: number; + reason: string; + generation: number; + socketOpened: boolean; + helloReceived: boolean; + connectRequestSent: boolean; + connectFailure?: { error: Error; reconnectDelayMs?: number }; +}; +type GatewayProtocolConnectDecision = { + closeCode: number; + closeReason: string; + reconnectDelayMs?: number; + stop?: boolean; + error?: Error; +}; +type GatewayProtocolCloseDecision = { + retry: boolean; + notify: boolean; + reconnectDelayMs?: number; + pendingError?: Error; +}; +export type GatewayProtocolTiming = { + phase: + | "socket-open" + | "challenge" + | "fallback" + | "device-identity-ready" + | "connect-plan-ready" + | "request-sent" + | "hello" + | "failed"; + generation: number; + durationMs: number; + phaseDurationMs: number; + hasChallenge: boolean; + usedFallback: boolean; + plan?: TPlan; + detail?: unknown; +}; +export type GatewayProtocolClientOptions = { + createSocket: (handlers: GatewayProtocolSocketHandlers) => GatewayProtocolSocket; + createRequestId: () => string; + createRequestError?: (error: Partial) => GatewayProtocolRequestError; + createRequestTimeoutError?: (method: string, timeoutMs: number, requestSent: boolean) => Error; + createRequestAbortError?: (method: string) => Error; + buildConnectPlan: (params: { + nonce: string | null; + challengeTs: number | null | undefined; + generation: number; + }) => TPlan | Promise; + buildConnectParams: (plan: TPlan) => unknown; + onConnectPlanError?: (error: Error) => GatewayProtocolConnectDecision; + onConnectHello?: (hello: HelloOk, context: GatewayProtocolConnectContext) => void; + onHello?: (hello: HelloOk) => void; + onConnectFailure?: ( + error: GatewayProtocolRequestError, + context: GatewayProtocolConnectContext, + ) => GatewayProtocolConnectDecision; + resolveClose: (context: GatewayProtocolCloseContext) => GatewayProtocolCloseDecision; + onClose?: (context: GatewayProtocolCloseContext, decision: GatewayProtocolCloseDecision) => void; + notifyStoppedClose?: boolean; + onConnectError?: (error: Error) => void; + onSocketFactoryError?: (error: Error) => void; + onParseError?: (error: unknown) => void; + onEvent?: (event: EventFrame) => void; + onGap?: (info: { expected: number; received: number }) => void; + onActivity?: () => void; + onTiming?: (timing: GatewayProtocolTiming) => void; + onRequestTiming?: (timing: GatewayProtocolRequestTiming) => void; + onCallbackError?: (label: string, error: unknown) => void; + handshake: + | { mode: "fallback"; timeoutMs: number } + | { + mode: "require-challenge"; + timeoutMs: number; + timeoutMessage?: (elapsedMs: number) => string; + }; + reconnect: { initialMs: number; multiplier: number; maxMs: number }; + requestTimeoutMs?: number; + nowMs?: () => number; + shouldRetrySocketFactoryError?: (error: Error) => boolean; + rethrowSocketFactoryError?: (error: Error) => boolean; +}; +export type ConnectTimingState = { + generation: number; + startedAtMs: number; + lastAtMs: number; + hasChallenge: boolean; + usedFallback: boolean; +}; +export type CloseSnapshot = Omit; diff --git a/packages/gateway-client/src/protocol-client.ts b/packages/gateway-client/src/protocol-client.ts index 8ce4ca530fe8..9e32a8516d49 100644 --- a/packages/gateway-client/src/protocol-client.ts +++ b/packages/gateway-client/src/protocol-client.ts @@ -1,4 +1,4 @@ -import type { ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol"; +import type { EventFrame, HelloOk } from "@openclaw/gateway-protocol"; import { isGatewayEventFrame, isGatewayResponseFrame, @@ -20,115 +20,21 @@ export { type GatewayProtocolRequestTiming, }; -export type GatewayProtocolSocket = { - isOpen: () => boolean; - send: (data: string) => void; - close: (code?: number, reason?: string) => void; -}; -export type GatewayProtocolSocketHandlers = { - open: () => void; - message: (data: string) => void; - close: (code: number, reason: string) => void; - error: (error: Error) => void; -}; -type GatewayProtocolConnectContext = { - generation: number; - nonce: string | null; - challengeTs: number | null | undefined; - plan: TPlan; -}; -export type GatewayProtocolCloseContext = { - code: number; - reason: string; - generation: number; - socketOpened: boolean; - helloReceived: boolean; - connectRequestSent: boolean; - connectFailure?: { error: Error; reconnectDelayMs?: number }; -}; -type GatewayProtocolConnectDecision = { - closeCode: number; - closeReason: string; - reconnectDelayMs?: number; - stop?: boolean; - error?: Error; -}; -type GatewayProtocolCloseDecision = { - retry: boolean; - notify: boolean; - reconnectDelayMs?: number; - pendingError?: Error; -}; -export type GatewayProtocolTiming = { - phase: - | "socket-open" - | "challenge" - | "fallback" - | "device-identity-ready" - | "connect-plan-ready" - | "request-sent" - | "hello" - | "failed"; - generation: number; - durationMs: number; - phaseDurationMs: number; - hasChallenge: boolean; - usedFallback: boolean; - plan?: TPlan; - detail?: unknown; -}; -type GatewayProtocolClientOptions = { - createSocket: (handlers: GatewayProtocolSocketHandlers) => GatewayProtocolSocket; - createRequestId: () => string; - createRequestError?: (error: Partial) => GatewayProtocolRequestError; - createRequestTimeoutError?: (method: string, timeoutMs: number, requestSent: boolean) => Error; - createRequestAbortError?: (method: string) => Error; - buildConnectPlan: (params: { - nonce: string | null; - challengeTs: number | null | undefined; - generation: number; - }) => TPlan | Promise; - buildConnectParams: (plan: TPlan) => unknown; - onConnectPlanError?: (error: Error) => GatewayProtocolConnectDecision; - onConnectHello?: (hello: HelloOk, context: GatewayProtocolConnectContext) => void; - onHello?: (hello: HelloOk) => void; - onConnectFailure?: ( - error: GatewayProtocolRequestError, - context: GatewayProtocolConnectContext, - ) => GatewayProtocolConnectDecision; - resolveClose: (context: GatewayProtocolCloseContext) => GatewayProtocolCloseDecision; - onClose?: (context: GatewayProtocolCloseContext, decision: GatewayProtocolCloseDecision) => void; - notifyStoppedClose?: boolean; - onConnectError?: (error: Error) => void; - onSocketFactoryError?: (error: Error) => void; - onParseError?: (error: unknown) => void; - onEvent?: (event: EventFrame) => void; - onGap?: (info: { expected: number; received: number }) => void; - onActivity?: () => void; - onTiming?: (timing: GatewayProtocolTiming) => void; - onRequestTiming?: (timing: GatewayProtocolRequestTiming) => void; - onCallbackError?: (label: string, error: unknown) => void; - handshake: - | { mode: "fallback"; timeoutMs: number } - | { - mode: "require-challenge"; - timeoutMs: number; - timeoutMessage?: (elapsedMs: number) => string; - }; - reconnect: { initialMs: number; multiplier: number; maxMs: number }; - requestTimeoutMs?: number; - nowMs?: () => number; - shouldRetrySocketFactoryError?: (error: Error) => boolean; - rethrowSocketFactoryError?: (error: Error) => boolean; -}; -type ConnectTimingState = { - generation: number; - startedAtMs: number; - lastAtMs: number; - hasChallenge: boolean; - usedFallback: boolean; -}; -type CloseSnapshot = Omit; +import type { + CloseSnapshot, + ConnectTimingState, + GatewayProtocolClientOptions, + GatewayProtocolCloseContext, + GatewayProtocolSocket, + GatewayProtocolTiming, +} from "./protocol-client-contract.js"; + +export type { + GatewayProtocolCloseContext, + GatewayProtocolSocket, + GatewayProtocolSocketHandlers, + GatewayProtocolTiming, +} from "./protocol-client-contract.js"; /** * Browser-safe gateway wire client. Environment adapters own transport and auth @@ -571,6 +477,7 @@ export class GatewayProtocolClient { if (!this.isActive(socket, generation) || this.connectSent) { return; } + this.connectFailure = { error }; this.opts.onConnectError?.(error); } diff --git a/src/cli/gateway-cli/register.option-collisions.test.ts b/src/cli/gateway-cli/register.option-collisions.test.ts index 81f0fdf8d817..c26e127a29a9 100644 --- a/src/cli/gateway-cli/register.option-collisions.test.ts +++ b/src/cli/gateway-cli/register.option-collisions.test.ts @@ -4,9 +4,21 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; import { registerGatewayCli } from "./register.js"; const mocks = vi.hoisted(() => ({ - callGatewayCli: vi.fn(async (_method: string, _opts: unknown, _params?: unknown) => ({ - ok: true, - })), + callGatewayCli: vi.fn(async (method: string, _opts: unknown, _params?: unknown) => { + if (method === "gateway.suspend.prepare") { + return { + status: "ready", + suspensionId: "suspension-1", + expiresAtMs: 1_800_000_000_000, + activeCount: 0, + blockers: [], + }; + } + if (method === "gateway.suspend.resume") { + return { ok: true, status: "running", resumed: true }; + } + return { ok: true }; + }), emitReachableGatewayAuthDiagnostic: vi.fn(async (_params: unknown) => false), formatHealthChannelLines: vi.fn(() => []), gatewayStatusCommand: vi.fn(async (_opts: unknown, _runtime: unknown) => {}), @@ -216,6 +228,32 @@ describe("gateway register option collisions", () => { expectLocalGatewayCall("health", 19085); }, }, + { + name: "projects gateway suspend --port and request id", + argv: ["gateway", "suspend", "--request-id", "host-operation", "--port", "19086", "--json"], + assert: () => { + expectLocalGatewayCall("gateway.suspend.prepare", 19086, { + requestId: "host-operation", + }); + expect(defaultRuntime.writeJson).toHaveBeenCalledWith( + expect.objectContaining({ status: "ready", requestId: "host-operation" }), + ); + }, + }, + { + name: "inherits parent --port for gateway resume", + argv: ["gateway", "--port", "19087", "resume", "suspension-1", "--json"], + assert: () => { + expectLocalGatewayCall("gateway.suspend.resume", 19087, { + suspensionId: "suspension-1", + }); + expect(defaultRuntime.writeJson).toHaveBeenCalledWith({ + ok: true, + status: "running", + resumed: true, + }); + }, + }, { name: "forwards --token to gateway probe when parent and child option names collide", argv: ["gateway", "probe", "--token", "tok_probe", "--json"], diff --git a/src/cli/gateway-cli/register.ts b/src/cli/gateway-cli/register.ts index b10ea56eb717..4643b0a9e85c 100644 --- a/src/cli/gateway-cli/register.ts +++ b/src/cli/gateway-cli/register.ts @@ -27,6 +27,7 @@ import type { GatewayDiscoverOpts } from "./discover.js"; import { isGatewayMachineOutput } from "./output-mode.js"; import { addGatewayRestartHandoffCommands } from "./register-restart-handoff.js"; import { addGatewayRunCommand } from "./run-command.js"; +import { runGatewayResume, runGatewaySuspend } from "./suspend-cli.js"; type GatewayRpcOpts = Parameters[1]; @@ -595,6 +596,54 @@ export function registerGatewayCli(program: Command, deps: GatewayCliDependencie }), ); + gatewayCallOpts( + gateway + .command("suspend") + .description("Prepare the Gateway for cooperative host suspension") + .option("--request-id ", "Stable suspension request id") + .option("--wait ", "Wait up to this many seconds for active work to drain") + .option("--port ", "Local Gateway port") + .action(async (opts, command) => { + await runGatewayCommand( + async () => { + const rpcOpts = await resolveGatewayRpcOptionsWithLocalPort(opts, command); + await runGatewaySuspend( + { + rpcOpts, + requestId: opts.requestId, + waitSeconds: opts.wait, + json: Boolean(rpcOpts.json), + }, + { callGateway: callGatewayCli, runtime: defaultRuntime }, + ); + }, + "Gateway suspend failed", + { json: Boolean(opts.json) }, + ); + }), + ); + + gatewayCallOpts( + gateway + .command("resume") + .description("Release a cooperative Gateway suspension") + .argument("", "Suspension id returned by gateway suspend") + .option("--port ", "Local Gateway port") + .action(async (suspensionId, opts, command) => { + await runGatewayCommand( + async () => { + const rpcOpts = await resolveGatewayRpcOptionsWithLocalPort(opts, command); + await runGatewayResume( + { rpcOpts, suspensionId: String(suspensionId), json: Boolean(rpcOpts.json) }, + { callGateway: callGatewayCli, runtime: defaultRuntime }, + ); + }, + "Gateway resume failed", + { json: Boolean(opts.json) }, + ); + }), + ); + gatewayCallOpts( gateway .command("usage-cost") diff --git a/src/cli/gateway-cli/suspend-cli.test.ts b/src/cli/gateway-cli/suspend-cli.test.ts new file mode 100644 index 000000000000..a5193f7fa706 --- /dev/null +++ b/src/cli/gateway-cli/suspend-cli.test.ts @@ -0,0 +1,169 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { OutputRuntimeEnv } from "../../runtime.js"; +import { runGatewayResume, runGatewaySuspend } from "./suspend-cli.js"; + +function createRuntime(): OutputRuntimeEnv { + return { + log: vi.fn(), + error: vi.fn(), + writeStdout: vi.fn(), + writeJson: vi.fn(), + exit: vi.fn(), + }; +} + +const readyResult = { + status: "ready" as const, + suspensionId: "suspension-1", + expiresAtMs: Date.parse("2026-08-11T12:00:00.000Z"), + activeCount: 0, + blockers: [], +}; + +const busyResult = { + status: "busy" as const, + reason: "active-work" as const, + retryAfterMs: 200, + activeCount: 1, + blockers: [{ kind: "root-request" as const, count: 1, message: "1 active request" }], +}; + +describe("gateway suspend CLI", () => { + beforeEach(() => vi.clearAllMocks()); + + it("prints a ready lease with the default CLI request id", async () => { + const callGateway = vi.fn(async () => readyResult); + const runtime = createRuntime(); + + await runGatewaySuspend({ rpcOpts: {} }, { callGateway, runtime }); + + expect(callGateway).toHaveBeenCalledWith( + "gateway.suspend.prepare", + {}, + { requestId: expect.stringMatching(/^cli-[0-9a-f]{8}$/u) }, + ); + expect(callGateway).toHaveBeenCalledOnce(); + expect(runtime.log).toHaveBeenCalledWith("Gateway suspension prepared."); + expect(runtime.log).toHaveBeenCalledWith("Suspension ID: suspension-1"); + expect(runtime.log).toHaveBeenCalledWith( + `Expires: 2026-08-11T12:00:00.000Z (${readyResult.expiresAtMs} ms)`, + ); + expect(runtime.log).toHaveBeenCalledWith("Resume with: openclaw gateway resume suspension-1"); + }); + + it("reports blockers without polling when --wait is omitted", async () => { + const callGateway = vi.fn(async () => busyResult); + + await expect( + runGatewaySuspend( + { rpcOpts: {}, requestId: "host-operation" }, + { callGateway, runtime: createRuntime() }, + ), + ).rejects.toThrow( + "Gateway suspension is busy (active-work; 1 active).\nBlockers:\n- 1 active request\nRetry later or use --wait .", + ); + expect(callGateway).toHaveBeenCalledOnce(); + }); + + it("polls with one stable request id until the Gateway is ready", async () => { + const callGateway = vi + .fn() + .mockResolvedValueOnce(busyResult) + .mockResolvedValueOnce(readyResult); + let now = 1_000; + const sleep = vi.fn(async (delayMs: number) => { + now += delayMs; + }); + + await runGatewaySuspend( + { rpcOpts: {}, requestId: "host-operation", waitSeconds: "2" }, + { callGateway, runtime: createRuntime(), nowMs: () => now, sleep }, + ); + + expect(sleep).toHaveBeenCalledExactlyOnceWith(200); + expect(callGateway).toHaveBeenCalledTimes(2); + expect(callGateway.mock.calls.map((call) => call[2])).toEqual([ + { requestId: "host-operation" }, + { requestId: "host-operation" }, + ]); + }); + + it("emits the latest busy result and exits nonzero in JSON mode", async () => { + const runtime = createRuntime(); + + await runGatewaySuspend( + { rpcOpts: { json: true }, requestId: "host-operation", json: true }, + { callGateway: vi.fn(async () => busyResult), runtime }, + ); + + expect(runtime.writeJson).toHaveBeenCalledWith({ + ...busyResult, + requestId: "host-operation", + }); + expect(runtime.exit).toHaveBeenCalledWith(1); + }); + + it("never issues another prepare after a sleep overshoots the deadline", async () => { + let now = 1_000; + const callGateway = vi.fn(async () => busyResult); + + await expect( + runGatewaySuspend( + { rpcOpts: {}, requestId: "host-operation", waitSeconds: "0.2" }, + { + callGateway, + runtime: createRuntime(), + nowMs: () => now, + sleep: async () => { + // A lagging clock can wake far past the advertised --wait window. + now += 10_000; + }, + }, + ), + ).rejects.toThrow("Timed out waiting for the Gateway to become idle."); + expect(callGateway).toHaveBeenCalledOnce(); + }); + + it("reports the latest blockers when the wait deadline expires", async () => { + let now = 1_000; + + await expect( + runGatewaySuspend( + { rpcOpts: {}, requestId: "host-operation", waitSeconds: "0.1" }, + { + callGateway: vi.fn(async () => busyResult), + runtime: createRuntime(), + nowMs: () => now, + sleep: async (delayMs) => { + now += delayMs; + }, + }, + ), + ).rejects.toThrow( + "Gateway suspension is busy (active-work; 1 active).\nBlockers:\n- 1 active request\nTimed out waiting for the Gateway to become idle.", + ); + }); +}); + +describe("gateway resume CLI", () => { + it.each([ + { resumed: true, message: "Gateway resumed." }, + { + resumed: false, + message: + "No matching suspension was held (lease already expired or resumed); gateway is running.", + }, + ])("prints the resumed=$resumed outcome", async ({ resumed, message }) => { + const runtime = createRuntime(); + const callGateway = vi.fn(async () => ({ ok: true, status: "running", resumed })); + + await runGatewayResume({ rpcOpts: {}, suspensionId: "suspension-1" }, { callGateway, runtime }); + + expect(callGateway).toHaveBeenCalledExactlyOnceWith( + "gateway.suspend.resume", + {}, + { suspensionId: "suspension-1" }, + ); + expect(runtime.log).toHaveBeenCalledExactlyOnceWith(message); + }); +}); diff --git a/src/cli/gateway-cli/suspend-cli.ts b/src/cli/gateway-cli/suspend-cli.ts new file mode 100644 index 000000000000..4700b2b0b362 --- /dev/null +++ b/src/cli/gateway-cli/suspend-cli.ts @@ -0,0 +1,157 @@ +import { randomBytes } from "node:crypto"; +import type { + GatewaySuspendPrepareResult, + GatewaySuspendResumeResult, +} from "../../../packages/gateway-protocol/src/index.js"; +import { colorize, isRich, theme } from "../../../packages/terminal-core/src/theme.js"; +import type { OutputRuntimeEnv } from "../../runtime.js"; +import type { callGatewayFromCliWithTransport } from "../gateway-rpc.js"; + +type SuspendRpcOpts = Parameters[1]; + +type SuspendRpcCall = (method: string, opts: SuspendRpcOpts, params?: unknown) => Promise; + +type SuspendCliDeps = { + callGateway: SuspendRpcCall; + runtime: OutputRuntimeEnv; + nowMs?: () => number; + sleep?: (delayMs: number) => Promise; +}; + +const MIN_SUSPEND_POLL_DELAY_MS = 50; + +function parseWaitMs(value: string | number | undefined): number | undefined { + if (value === undefined) { + return undefined; + } + const seconds = typeof value === "number" ? value : Number(value.trim()); + if (!Number.isFinite(seconds) || seconds < 0) { + throw new Error("--wait must be a non-negative number of seconds"); + } + const milliseconds = Math.floor(seconds * 1_000); + if (!Number.isSafeInteger(milliseconds)) { + throw new Error("--wait is too large"); + } + return milliseconds; +} + +function resolveRequestId(value: string | undefined): string { + if (value === undefined) { + return `cli-${randomBytes(4).toString("hex")}`; + } + const requestId = value.trim(); + if (!requestId || requestId.length > 128) { + throw new Error("--request-id must contain 1 to 128 characters"); + } + return requestId; +} + +function formatBusyResult( + result: Extract, +): string { + const blockers = result.blockers.map((blocker) => `- ${blocker.message}`); + return [ + `Gateway suspension is busy (${result.reason}; ${result.activeCount} active).`, + ...(blockers.length > 0 ? ["Blockers:", ...blockers] : []), + ].join("\n"); +} + +function writeSuspendJson( + runtime: OutputRuntimeEnv, + result: GatewaySuspendPrepareResult, + requestId: string, +): void { + runtime.writeJson({ ...result, requestId }); +} + +export async function runGatewaySuspend( + options: { + rpcOpts: SuspendRpcOpts; + requestId?: string; + waitSeconds?: string | number; + json?: boolean; + }, + deps: SuspendCliDeps, +): Promise { + const nowMs = deps.nowMs ?? Date.now; + const sleep = + deps.sleep ?? + (async (delayMs: number) => + await new Promise((resolve) => { + setTimeout(resolve, delayMs); + })); + const requestId = resolveRequestId(options.requestId); + const waitMs = parseWaitMs(options.waitSeconds); + const deadlineMs = waitMs === undefined ? undefined : nowMs() + waitMs; + const maxAttempts = waitMs === undefined ? 1 : Math.ceil(waitMs / MIN_SUSPEND_POLL_DELAY_MS) + 1; + let latest: GatewaySuspendPrepareResult | undefined; + + for (let attempt = 0; attempt < maxAttempts; attempt += 1) { + // A sleep can overshoot the deadline; never issue a prepare that could + // suspend the Gateway after the operator's advertised --wait window. + if (attempt > 0 && deadlineMs !== undefined && nowMs() >= deadlineMs) { + break; + } + latest = (await deps.callGateway("gateway.suspend.prepare", options.rpcOpts, { + requestId, + })) as GatewaySuspendPrepareResult; + if (latest.status === "ready") { + if (options.json) { + writeSuspendJson(deps.runtime, latest, requestId); + return; + } + const rich = isRich(); + deps.runtime.log(colorize(rich, theme.success, "Gateway suspension prepared.")); + deps.runtime.log(`${colorize(rich, theme.muted, "Suspension ID:")} ${latest.suspensionId}`); + deps.runtime.log( + `${colorize(rich, theme.muted, "Expires:")} ${new Date(latest.expiresAtMs).toISOString()} (${latest.expiresAtMs} ms)`, + ); + deps.runtime.log(`Resume with: openclaw gateway resume ${latest.suspensionId}`); + return; + } + + if (deadlineMs === undefined) { + if (options.json) { + writeSuspendJson(deps.runtime, latest, requestId); + deps.runtime.exit(1); + return; + } + throw new Error(`${formatBusyResult(latest)}\nRetry later or use --wait .`); + } + + const remainingMs = deadlineMs - nowMs(); + if (remainingMs <= 0) { + break; + } + const delayMs = Math.min(remainingMs, Math.max(MIN_SUSPEND_POLL_DELAY_MS, latest.retryAfterMs)); + await sleep(delayMs); + } + + if (!latest || latest.status !== "busy") { + throw new Error("Gateway suspension polling ended without a result"); + } + if (options.json) { + writeSuspendJson(deps.runtime, latest, requestId); + deps.runtime.exit(1); + return; + } + throw new Error(`${formatBusyResult(latest)}\nTimed out waiting for the Gateway to become idle.`); +} + +export async function runGatewayResume( + options: { rpcOpts: SuspendRpcOpts; suspensionId: string; json?: boolean }, + deps: Pick, +): Promise { + const result = (await deps.callGateway("gateway.suspend.resume", options.rpcOpts, { + suspensionId: options.suspensionId, + })) as GatewaySuspendResumeResult; + if (options.json) { + deps.runtime.writeJson(result); + return; + } + deps.runtime.log( + result.resumed + ? "Gateway resumed." + : "No matching suspension was held (lease already expired or resumed); gateway is running.", + ); +} diff --git a/src/gateway/call.test.ts b/src/gateway/call.test.ts index e8a87306eaf3..d27a71674e46 100644 --- a/src/gateway/call.test.ts +++ b/src/gateway/call.test.ts @@ -1703,6 +1703,34 @@ describe("callGateway error details", () => { }); }); + it("surfaces a websocket upgrade rejection carried by close info", async () => { + startMode = "silent"; + setLocalLoopbackGatewayConfig(); + const upgradeError = Object.assign( + new Error( + "gateway rejected websocket upgrade (HTTP 503): Gateway websocket admission closed", + ), + { + name: "GatewayClientRequestError", + gatewayCode: "UNAVAILABLE", + details: { reason: "websocket-upgrade-rejected", httpStatus: 503 }, + retryable: true, + }, + ); + + const request = callGateway({ method: "health" }); + await waitForFast(() => expect(lastClientOptions).not.toBeNull()); + lastClientOptions?.onClose?.(1006, "", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + transientPreHelloCleanClose: false, + connectError: upgradeError, + }); + + await expect(request).rejects.toBe(upgradeError); + }); + it.each([ { name: "another structured auth rejection", diff --git a/src/gateway/call.ts b/src/gateway/call.ts index dd18b956761d..df7a9bade273 100644 --- a/src/gateway/call.ts +++ b/src/gateway/call.ts @@ -984,6 +984,11 @@ async function executeGatewayRequestWithScopes(params: { if (settled || ignoreClose) { return; } + if (info?.connectError) { + ignoreClose = true; + stop(info.connectError); + return; + } if ( !primaryRequestStarted && info?.transientPreHelloCleanClose === true && diff --git a/src/gateway/client.test.ts b/src/gateway/client.test.ts index b07ae3a0e43a..a2fee29aa28e 100644 --- a/src/gateway/client.test.ts +++ b/src/gateway/client.test.ts @@ -809,6 +809,7 @@ describe("GatewayClient close handling", () => { expect.objectContaining({ message: "gateway tls fingerprint mismatch" }), ); expect(onClose).toHaveBeenCalledWith(1008, "gateway tls fingerprint mismatch", { + connectError: expect.objectContaining({ message: "gateway tls fingerprint mismatch" }), phase: "pre-hello", socketOpened: true, transportValidated: false, @@ -2591,6 +2592,11 @@ describe("GatewayClient connect auth payload", () => { "gateway client reconnect paused handler error: Error: paused callback failed", ); expect(onClose).toHaveBeenCalledWith(1008, "connect failed", { + connectError: expect.objectContaining({ + details: { code: "AUTH_TOKEN_MISSING" }, + gatewayCode: "INVALID_REQUEST", + message: "unauthorized", + }), phase: "pre-hello", socketOpened: true, transportValidated: true, diff --git a/src/gateway/probe.device-auth-scope.test.ts b/src/gateway/probe.device-auth-scope.test.ts index 2d64190c7569..deda900418d0 100644 --- a/src/gateway/probe.device-auth-scope.test.ts +++ b/src/gateway/probe.device-auth-scope.test.ts @@ -7,7 +7,7 @@ import { loadOrCreateDeviceIdentity } from "../infra/device-identity.js"; import { closeOpenClawStateDatabaseForTest } from "../state/openclaw-state-db.js"; import { withTempDir } from "../test-utils/temp-dir.js"; -type WebSocketEvent = "open" | "message" | "close" | "error"; +type WebSocketEvent = "open" | "message" | "close" | "error" | "unexpected-response"; const webSockets = vi.hoisted((): ProbeWebSocket[] => []); @@ -25,6 +25,7 @@ class ProbeWebSocket { message: [], close: [], error: [], + "unexpected-response": [], }; constructor(_url: string, _options?: unknown) { diff --git a/src/gateway/server-http.ts b/src/gateway/server-http.ts index 3daacb523957..8d3307ecb8a2 100644 --- a/src/gateway/server-http.ts +++ b/src/gateway/server-http.ts @@ -18,7 +18,11 @@ import { createDiagnosticTraceContext, runWithDiagnosticTraceContext, } from "../infra/diagnostic-trace-context.js"; -import { isGatewayWorkAdmissionClosed } from "../process/gateway-work-admission.js"; +import { + getGatewaySuspendAdmissionPhase, + isGatewayRestartDraining, + isGatewayWorkAdmissionClosed, +} from "../process/gateway-work-admission.js"; import { createLazyRuntimeModule } from "../shared/lazy-runtime.js"; import { resolveAssistantIdentity } from "./assistant-identity.js"; import type { AuthRateLimiter } from "./auth-rate-limit.js"; @@ -782,7 +786,12 @@ function handleBudgetedGatewayWebSocketUpgrade(params: { prepareSocket?: (socket: GatewayIngressWebSocket) => void; }): void { const { req, socket, head, wss, preauthConnectionBudget, preauthBudgetKey, ingressName } = params; - if (isGatewayWorkAdmissionClosed()) { + if ( + isGatewayWorkAdmissionClosed() && + (ingressName === "Worker" || + isGatewayRestartDraining() || + getGatewaySuspendAdmissionPhase() !== "prepared") + ) { writeGatewayUpgradeServiceUnavailable(socket, `${ingressName} websocket admission closed`); socket.destroy(); return; @@ -962,8 +971,7 @@ export function attachGatewayUpgradeHandler(opts: { return; } // Plugin-owned upgrade routes have already had the opportunity to claim the socket. - // Core Gateway upgrades must stop at the HTTP boundary so a client cannot hold an - // untracked pre-connect socket after suspension or restart admission closes. + // Core Gateway control connections remain reachable while suspension is prepared. try { handleBudgetedGatewayWebSocketUpgrade({ req, diff --git a/src/gateway/server.preauth-hardening.test.ts b/src/gateway/server.preauth-hardening.test.ts index 3cce6ab91376..d18ae25f3291 100644 --- a/src/gateway/server.preauth-hardening.test.ts +++ b/src/gateway/server.preauth-hardening.test.ts @@ -9,7 +9,11 @@ import { resetDiagnosticEventsForTest, type DiagnosticEventPayload, } from "../infra/diagnostic-events.js"; -import { tryBeginGatewaySuspendAdmission } from "../process/gateway-work-admission.js"; +import { + markGatewayRestartDraining, + resetGatewayWorkAdmission, + tryBeginGatewaySuspendAdmission, +} from "../process/gateway-work-admission.js"; import { captureEnv, setTestEnvValue } from "../test-utils/env.js"; import type { ResolvedGatewayAuth } from "./auth.js"; import { MAX_PREAUTH_PAYLOAD_BYTES } from "./server-constants.js"; @@ -43,6 +47,7 @@ const PREAUTH_HANDSHAKE_TEST_CLOSE_LIMIT_MS = 5_000; const cleanupEnv: Array<() => void> = []; afterEach(async () => { + resetGatewayWorkAdmission(); while (cleanupEnv.length > 0) { cleanupEnv.pop()?.(); } @@ -152,6 +157,39 @@ describe("gateway pre-auth hardening", () => { } }); + it("rejects worker websocket upgrades after suspension is prepared", async () => { + const httpServer = http.createServer(); + const wss = new WebSocketServer({ maxPayload: 1024, noServer: true }); + wss.on("connection", (socket) => socket.close()); + attachWorkerGatewayUpgradeHandler({ + httpServer, + wss, + preauthConnectionBudget: createPreauthConnectionBudget(1), + }); + await new Promise((resolve) => { + httpServer.listen(0, "127.0.0.1", resolve); + }); + const address = httpServer.address(); + const port = typeof address === "object" && address ? address.port : 0; + const suspension = tryBeginGatewaySuspendAdmission(() => {}); + expect(suspension?.commit()).toBe(true); + + try { + await expect(requestUpgradeRejection(port)).resolves.toEqual({ + status: 503, + body: "Worker websocket admission closed", + }); + } finally { + suspension?.release(); + await new Promise((resolve) => { + wss.close(() => resolve()); + }); + await new Promise((resolve, reject) => { + httpServer.close((error) => (error ? reject(error) : resolve())); + }); + } + }); + it("rejects upgrades before websocket handlers attach (pre-auth budget enforced, then released)", async () => { const clients = new Set(); const resolvedAuth: ResolvedGatewayAuth = { mode: "none", allowTailscale: false }; @@ -196,18 +234,49 @@ describe("gateway pre-auth hardening", () => { } }); - it("rejects core websocket upgrades while suspension admission is closed", async () => { + it("accepts core websocket upgrades after suspension is prepared", async () => { const harness = await createGatewaySuiteHarness(); const suspension = tryBeginGatewaySuspendAdmission(() => {}); expect(suspension?.commit()).toBe(true); + try { + const ws = await harness.openWs(); + await expect(readConnectChallengeNonce(ws)).resolves.toEqual(expect.any(String)); + ws.close(); + await new Promise((resolve) => { + ws.once("close", () => resolve()); + }); + } finally { + suspension?.release(); + await harness.close(); + } + }); + + it("rejects core websocket upgrades while suspension is preparing", async () => { + const harness = await createGatewaySuiteHarness(); + const suspension = tryBeginGatewaySuspendAdmission(() => {}); + + try { + await expect(requestUpgradeRejection(harness.port)).resolves.toEqual({ + status: 503, + body: "Gateway websocket admission closed", + }); + } finally { + suspension?.rollback(); + await harness.close(); + } + }); + + it("rejects core websocket upgrades during restart drain", async () => { + const harness = await createGatewaySuiteHarness(); + markGatewayRestartDraining(); + try { await expect(requestUpgradeRejection(harness.port)).resolves.toEqual({ status: 503, body: "Gateway websocket admission closed", }); } finally { - suspension?.release(); await harness.close(); } }); diff --git a/src/gateway/server/ws-connection/message-handler.suspension-admission.test.ts b/src/gateway/server/ws-connection/message-handler.suspension-admission.test.ts index 8868483ad56c..89a211edf947 100644 --- a/src/gateway/server/ws-connection/message-handler.suspension-admission.test.ts +++ b/src/gateway/server/ws-connection/message-handler.suspension-admission.test.ts @@ -5,6 +5,7 @@ import type { WebSocket } from "ws"; import { PROTOCOL_VERSION } from "../../../../packages/gateway-protocol/src/index.js"; import { getActiveGatewayRootWorkCount, + markGatewayRestartDraining, resetGatewayWorkAdmission, tryBeginGatewaySuspendAdmission, } from "../../../process/gateway-work-admission.js"; @@ -149,6 +150,27 @@ function attachHarness(params: { deferSocketSend?: boolean } = {}) { }, }), ), + sendNodeConnect: () => + onMessage?.( + JSON.stringify({ + type: "req", + id: "node-connect-1", + method: "connect", + params: { + minProtocol: PROTOCOL_VERSION, + maxProtocol: PROTOCOL_VERSION, + client: { + id: "gateway-client", + version: "dev", + platform: "test", + mode: "backend", + }, + role: "node", + scopes: [], + caps: [], + }, + }), + ), sendWorkerConnect: () => onMessage?.( JSON.stringify({ @@ -173,54 +195,106 @@ beforeEach(() => { afterEach(resetGatewayWorkAdmission); describe("WebSocket connect suspension admission", () => { - it.each(["preparing", "prepared"] as const)( - "rejects a validated connect while suspension is %s before session mutations", - async (phase) => { - const suspension = tryBeginGatewaySuspendAdmission(() => {}); - expect(suspension).not.toBeNull(); - if (phase === "prepared") { - expect(suspension?.commit()).toBe(true); - } - const harness = attachHarness(); + it("rejects a validated connect while suspension is preparing before session mutations", async () => { + const suspension = tryBeginGatewaySuspendAdmission(() => {}); + expect(suspension).not.toBeNull(); + const harness = attachHarness(); - harness.sendConnect(); + harness.sendConnect(); - await vi.waitFor(() => { - expect(harness.socketSend).toHaveBeenCalledOnce(); - }); - const response = JSON.parse(harness.socketSend.mock.calls[0]?.[0] ?? "{}") as { - error?: { - code?: string; - retryable?: boolean; - retryAfterMs?: number; - details?: Record; - }; + await vi.waitFor(() => { + expect(harness.socketSend).toHaveBeenCalledOnce(); + }); + const response = JSON.parse(harness.socketSend.mock.calls[0]?.[0] ?? "{}") as { + error?: { + code?: string; + retryable?: boolean; + retryAfterMs?: number; + details?: Record; }; - expect(response.error).toMatchObject({ - code: "UNAVAILABLE", - retryable: true, - retryAfterMs: 1_000, - details: { - method: "connect", - reason: "gateway-suspending", - phase, - }, - }); - expect(harness.client).toBeNull(); - expect(harness.setClient).not.toHaveBeenCalled(); - expect(upsertPresenceMock).not.toHaveBeenCalled(); - expect(incrementPresenceVersionMock).not.toHaveBeenCalled(); - await vi.waitFor(() => { - expect(harness.close).toHaveBeenCalledWith(1013, "gateway suspension in progress"); - }); + }; + expect(response.error).toMatchObject({ + code: "UNAVAILABLE", + retryable: true, + retryAfterMs: 1_000, + details: { + method: "connect", + reason: "gateway-suspending", + phase: "preparing", + }, + }); + expect(harness.client).toBeNull(); + expect(harness.setClient).not.toHaveBeenCalled(); + expect(upsertPresenceMock).not.toHaveBeenCalled(); + expect(incrementPresenceVersionMock).not.toHaveBeenCalled(); + await vi.waitFor(() => { + expect(harness.close).toHaveBeenCalledWith(1013, "gateway suspension in progress"); + }); + suspension?.rollback(); + }); - if (phase === "prepared") { - suspension?.release(); - } else { - suspension?.rollback(); - } - }, - ); + it("accepts a validated connect while suspension is prepared", async () => { + const suspension = tryBeginGatewaySuspendAdmission(() => {}); + expect(suspension?.commit()).toBe(true); + const harness = attachHarness(); + + harness.sendConnect(); + + await vi.waitFor(() => { + expect(harness.setClient).toHaveBeenCalledOnce(); + }); + expect(harness.client).not.toBeNull(); + expect(harness.close).not.toHaveBeenCalled(); + suspension?.release(); + }); + + it("rejects a node connect while suspension is prepared", async () => { + const suspension = tryBeginGatewaySuspendAdmission(() => {}); + expect(suspension?.commit()).toBe(true); + const harness = attachHarness(); + + harness.sendNodeConnect(); + + await vi.waitFor(() => { + expect(harness.socketSend).toHaveBeenCalledOnce(); + }); + const response = JSON.parse(harness.socketSend.mock.calls[0]?.[0] ?? "{}") as { + error?: { details?: Record }; + }; + expect(response.error?.details).toMatchObject({ + method: "connect", + reason: "gateway-suspending", + phase: "prepared", + }); + expect(harness.setClient).not.toHaveBeenCalled(); + expect(upsertPresenceMock).not.toHaveBeenCalled(); + await vi.waitFor(() => { + expect(harness.close).toHaveBeenCalledWith(1013, "gateway suspension in progress"); + }); + suspension?.release(); + }); + + it("rejects a validated connect during restart drain", async () => { + markGatewayRestartDraining(); + const harness = attachHarness(); + + harness.sendConnect(); + + await vi.waitFor(() => { + expect(harness.socketSend).toHaveBeenCalledOnce(); + }); + const response = JSON.parse(harness.socketSend.mock.calls[0]?.[0] ?? "{}") as { + error?: { details?: Record }; + }; + expect(response.error?.details).toMatchObject({ + method: "connect", + reason: "gateway-restarting", + }); + expect(harness.setClient).not.toHaveBeenCalled(); + await vi.waitFor(() => { + expect(harness.close).toHaveBeenCalledWith(1013, "gateway restart in progress"); + }); + }); it("keeps an accepted handshake visible as root work until hello is sent", async () => { const harness = attachHarness({ deferSocketSend: true }); diff --git a/src/gateway/server/ws-connection/message-handler.ts b/src/gateway/server/ws-connection/message-handler.ts index 560c034b559d..6aa2d785801b 100644 --- a/src/gateway/server/ws-connection/message-handler.ts +++ b/src/gateway/server/ws-connection/message-handler.ts @@ -402,21 +402,38 @@ export function attachGatewayWsMessageHandler(params: GatewayWsMessageHandlerPar } }; - const rejectConnectForClosedAdmission = async (data: RawData): Promise => { + const parsePreauthConnectFrame = (data: RawData) => { if (isClosed() || rawDataByteLength(data) > MAX_PREAUTH_PAYLOAD_BYTES) { - return false; + return null; } let parsed: unknown; try { parsed = JSON.parse(rawDataToString(data)); } catch { - return false; + return null; } if ( !validateRequestFrame(parsed) || parsed.method !== "connect" || !validateConnectParams(parsed.params) ) { + return null; + } + return parsed; + }; + + const isPreparedControlConnect = (data: RawData): boolean => { + const parsed = parsePreauthConnectFrame(data); + if (!parsed) { + return false; + } + const connectParams = parsed.params as { role?: unknown }; + return connectParams.role !== "node" && !claimsWorkerConnectionIdentity(parsed.params); + }; + + const rejectConnectForClosedAdmission = async (data: RawData): Promise => { + const parsed = parsePreauthConnectFrame(data); + if (!parsed) { return false; } @@ -457,6 +474,18 @@ export function attachGatewayWsMessageHandler(params: GatewayWsMessageHandlerPar } const admission = tryBeginGatewayRootWorkAdmission(); if (!admission) { + if ( + !isGatewayRestartDraining() && + getGatewaySuspendAdmissionPhase() === "prepared" && + isPreparedControlConnect(data) + ) { + // Refuse-only suspension fences work, not control-plane visibility. Only + // operator connects are admitted while prepared, and they can only reach + // suspend-control methods after handshake; node and worker connects would + // attach presence/registry state, so they stay refused. + await handleMessage(data); + return; + } if (await rejectConnectForClosedAdmission(data)) { return; } From 526ae6d94405d89df70d503f59b0997488f2b612 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 11 Aug 2026 22:12:56 -0700 Subject: [PATCH 025/165] fix(macos): honor While Using location permission (#122435) --- .../OpenClaw/NodeMode/MacNodeRuntime.swift | 11 ++----- .../MacNodeRuntimeTests.swift | 29 ++++++++++++++++++- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/apps/macos/Sources/OpenClaw/NodeMode/MacNodeRuntime.swift b/apps/macos/Sources/OpenClaw/NodeMode/MacNodeRuntime.swift index 16d4a38d7d2f..646d4e9e45ed 100644 --- a/apps/macos/Sources/OpenClaw/NodeMode/MacNodeRuntime.swift +++ b/apps/macos/Sources/OpenClaw/NodeMode/MacNodeRuntime.swift @@ -500,14 +500,9 @@ extension MacNodeRuntime { (Self.locationPreciseEnabled() ? .precise : .balanced) let services = await mainActorServices() let status = await services.locationAuthorizationStatus() - let hasPermission = switch mode { - case .always: - status == .authorizedAlways - case .whileUsing: - status == .authorizedAlways - case .off: - false - } + let hasPermission = PermissionManager.isLocationAuthorized( + status: status, + requireAlways: mode == .always) if !hasPermission { return BridgeInvokeResponse( id: req.id, diff --git a/apps/macos/Tests/OpenClawIPCTests/MacNodeRuntimeTests.swift b/apps/macos/Tests/OpenClawIPCTests/MacNodeRuntimeTests.swift index abfb06a1af18..f8b849787b2e 100644 --- a/apps/macos/Tests/OpenClawIPCTests/MacNodeRuntimeTests.swift +++ b/apps/macos/Tests/OpenClawIPCTests/MacNodeRuntimeTests.swift @@ -130,6 +130,7 @@ struct MacNodeRuntimeTests { var actError: Error? var performCallCount = 0 var releaseCallCount = 0 + var locationStatus: CLAuthorizationStatus var receivedLifecycleGenerations: [UInt64] = [] var receivedReleaseGenerations: [UInt64] = [] private let snapshotInspection: SnapshotInspection? @@ -147,6 +148,7 @@ struct MacNodeRuntimeTests { snapshotError: Error? = nil, snapshotInspection: SnapshotInspection? = nil, actError: Error? = nil, + locationAuthorizationStatus: CLAuthorizationStatus = .authorizedAlways, performEnteredGate: AsyncTestGate? = nil, allowPerformGate: AsyncTestGate? = nil) { @@ -154,6 +156,7 @@ struct MacNodeRuntimeTests { self.snapshotError = snapshotError self.snapshotInspection = snapshotInspection self.actError = actError + self.locationStatus = locationAuthorizationStatus self.performEnteredGate = performEnteredGate self.allowPerformGate = allowPerformGate } @@ -192,7 +195,7 @@ struct MacNodeRuntimeTests { } func locationAuthorizationStatus() -> CLAuthorizationStatus { - .authorizedAlways + self.locationStatus } func locationAccuracyAuthorization() -> CLAccuracyAuthorization { @@ -453,6 +456,30 @@ struct MacNodeRuntimeTests { } } + @Test func `handle location invoke applies authorization required by mode`() async throws { + let authorizedWhenInUse = try #require(CLAuthorizationStatus(rawValue: 4)) + let cases: [(mode: OpenClawLocationMode, status: CLAuthorizationStatus, accepted: Bool)] = [ + (.whileUsing, authorizedWhenInUse, true), + (.always, authorizedWhenInUse, false), + (.whileUsing, .authorizedAlways, true), + (.always, .authorizedAlways, true), + ] + + for testCase in cases { + await TestIsolation.withUserDefaultsValues([locationModeKey: testCase.mode.rawValue]) { + let services = await MainActor.run { + MainActorServicesProbe(locationAuthorizationStatus: testCase.status) + } + let runtime = MacNodeRuntime(makeMainActorServices: { services }) + + let response = await self.invoke( + runtime, "req-location", OpenClawLocationCommand.get.rawValue) + + #expect(response.ok == testCase.accepted) + } + } + } + @Test func `handle invoke screen record uses injected services`() async throws { let services = await MainActor.run { MainActorServicesProbe() } let runtime = MacNodeRuntime(makeMainActorServices: { services }) From 0295b7ab54f2767019b4d0a8188313920e81ed3d Mon Sep 17 00:00:00 2001 From: "Vyctor H. Brzezowski" Date: Wed, 12 Aug 2026 02:14:47 -0300 Subject: [PATCH 026/165] fix(ui): gate model shortcuts by search focus (#122316) * improve(ui): unify model picker shortcut hints * fix(ui): gate model shortcuts by search focus * fix(ui): focus model trigger on open --- .../chat-composer-accessory-focus.e2e.test.ts | 48 +++++++-------- .../chat-flow.models-reasoning.e2e.test.ts | 3 +- ...-session-page.workspace-memory.e2e.test.ts | 59 +++++++++++++++++++ .../chat/components/chat-model-picker.ts | 23 +++++--- ui/src/styles/chat/layout.css | 21 +++---- ui/src/styles/layout.css | 3 +- 6 files changed, 114 insertions(+), 43 deletions(-) diff --git a/ui/src/e2e/chat-composer-accessory-focus.e2e.test.ts b/ui/src/e2e/chat-composer-accessory-focus.e2e.test.ts index eae397457712..884466d19e90 100644 --- a/ui/src/e2e/chat-composer-accessory-focus.e2e.test.ts +++ b/ui/src/e2e/chat-composer-accessory-focus.e2e.test.ts @@ -9,7 +9,7 @@ const suite = createControlUiE2eSuite({ }); suite.define(() => { - it("keeps focus in place when pointer-opening passive composer popovers", async () => { + it("routes focus by composer accessory purpose", async () => { await suite.withPage({ viewport: { width: 1440, height: 900 } }, async ({ page }) => { const gateway = await installMockGateway(page, { models: [{ id: "gpt-5.6", name: "GPT-5.6", provider: "openai" }], @@ -114,28 +114,30 @@ suite.define(() => { await trigger.press("Enter"); } - for (const popover of [ - { - focus: ".chat-controls__model-search", - trigger: ".chat-controls__model-picker > summary", - }, - { - focus: ".agent-chat__attach-menu-option", - trigger: ".agent-chat__input-btn--attach", - }, - ]) { - await outside.focus(); - await composer.locator(popover.trigger).click(); - await expect - .poll(() => - page - .locator(popover.focus) - .first() - .evaluate((element) => document.activeElement === element), - ) - .toBe(true); - await page.keyboard.press("Escape"); - } + const modelTrigger = composer.locator(".chat-controls__model-picker > summary"); + await outside.focus(); + await modelTrigger.click(); + expect(await modelTrigger.evaluate((element) => document.activeElement === element)).toBe( + true, + ); + expect( + await page + .locator(".chat-controls__model-search") + .evaluate((element) => document.activeElement === element), + ).toBe(false); + await page.keyboard.press("Escape"); + + await outside.focus(); + await composer.locator(".agent-chat__input-btn--attach").click(); + await expect + .poll(() => + page + .locator(".agent-chat__attach-menu-option") + .first() + .evaluate((element) => document.activeElement === element), + ) + .toBe(true); + await page.keyboard.press("Escape"); }); }); }); diff --git a/ui/src/e2e/chat-flow.models-reasoning.e2e.test.ts b/ui/src/e2e/chat-flow.models-reasoning.e2e.test.ts index 119e0d17d61c..b3db40d0e36a 100644 --- a/ui/src/e2e/chat-flow.models-reasoning.e2e.test.ts +++ b/ui/src/e2e/chat-flow.models-reasoning.e2e.test.ts @@ -530,7 +530,8 @@ suite.define(() => { const search = main.locator('[data-chat-model-search="true"]'); await expect .poll(() => search.evaluate((element) => element === document.activeElement)) - .toBe(true); + .toBe(false); + await search.focus(); await search.fill("anthropic"); const anthropicModel = main.locator('[data-chat-model-option="anthropic/claude-fable-5"]'); await expect.poll(() => anthropicModel.isVisible()).toBe(true); diff --git a/ui/src/e2e/new-session-page.workspace-memory.e2e.test.ts b/ui/src/e2e/new-session-page.workspace-memory.e2e.test.ts index 6334e135ff35..20a59f391b28 100644 --- a/ui/src/e2e/new-session-page.workspace-memory.e2e.test.ts +++ b/ui/src/e2e/new-session-page.workspace-memory.e2e.test.ts @@ -235,6 +235,65 @@ suite.define(() => { }); }); + it("separates model shortcuts from numeric search input by focus", async () => { + await withNewSessionPage(DESKTOP_CONTEXT, async (page) => { + await installMockGateway(page, { models: MODELS }); + await page.goto(`${suite.server.baseUrl}new`); + + const modelSelect = page.locator('[data-chat-model-select="true"]'); + const picker = page.locator(".chat-controls__model-picker"); + const search = page.locator('[data-chat-model-search="true"]'); + const firstModel = page.locator('[data-chat-model-option="openai/gpt-5.5"]'); + const secondModel = page.locator('[data-chat-model-option="anthropic/claude-sonnet-4-6"]'); + + await modelSelect.click(); + await expect.poll(() => picker.getAttribute("open")).toBe(""); + await expect + .poll(() => modelSelect.evaluate((element) => element === document.activeElement)) + .toBe(true); + const secondShortcut = secondModel.locator('[data-chat-model-shortcut-number="2"]'); + await expect.poll(() => secondShortcut.count()).toBe(1); + const menuBoxBeforeFocus = await page.locator(".chat-controls__model-menu").boundingBox(); + const actionBoxBeforeFocus = await secondModel + .locator(".chat-controls__model-option-action") + .boundingBox(); + expect(menuBoxBeforeFocus).not.toBeNull(); + expect(actionBoxBeforeFocus).not.toBeNull(); + await expect + .poll(() => secondShortcut.evaluate((element) => getComputedStyle(element).opacity)) + .toBe("1"); + + await search.focus(); + await expect + .poll(() => search.evaluate((element) => element === document.activeElement)) + .toBe(true); + await expect + .poll(() => secondShortcut.evaluate((element) => getComputedStyle(element).opacity)) + .toBe("0"); + expect(await page.locator(".chat-controls__model-menu").boundingBox()).toEqual( + menuBoxBeforeFocus, + ); + expect( + await secondModel.locator(".chat-controls__model-option-action").boundingBox(), + ).toEqual(actionBoxBeforeFocus); + await search.press("1"); + await expect.poll(() => search.inputValue()).toBe("1"); + await expect.poll(() => picker.getAttribute("open")).toBe(""); + + await search.fill("anthropic"); + await expect.poll(() => firstModel.isVisible()).toBe(false); + await expect.poll(() => secondModel.isVisible()).toBe(true); + await modelSelect.focus(); + const filteredShortcut = secondModel.locator('[data-chat-model-shortcut-number="1"]'); + await expect + .poll(() => filteredShortcut.evaluate((element) => getComputedStyle(element).opacity)) + .toBe("1"); + await page.keyboard.press("1"); + await expect.poll(() => picker.getAttribute("open")).toBe(null); + await expect.poll(() => modelSelect.textContent()).toContain("Claude Sonnet 4.6"); + }); + }); + it("keeps the effort label, slider stop, and create payload aligned after a model switch", async () => { await withNewSessionPage(DESKTOP_CONTEXT, async (page) => { const levels = (ids: string[]) => ids.map((id) => ({ id, label: id })); diff --git a/ui/src/pages/chat/components/chat-model-picker.ts b/ui/src/pages/chat/components/chat-model-picker.ts index 640cc5eb7bd4..a893f59ea6c2 100644 --- a/ui/src/pages/chat/components/chat-model-picker.ts +++ b/ui/src/pages/chat/components/chat-model-picker.ts @@ -91,8 +91,8 @@ function pickerMenu(target: EventTarget | null): HTMLElement | null { : null; } -function visibleModelRows(menu: HTMLElement): HTMLButtonElement[] { - return [...menu.querySelectorAll("[data-chat-model-option]")] +function visibleModelRows(root: HTMLElement): HTMLButtonElement[] { + return [...root.querySelectorAll("[data-chat-model-option]")] .filter((row) => !row.hidden) .toSorted( (left, right) => @@ -234,11 +234,6 @@ function handleModelSearchKeydown(event: KeyboardEvent): void { if (rows.length === 0) { return; } - if (/^[1-9]$/u.test(event.key) && input.value === "") { - event.preventDefault(); - rows[Number(event.key) - 1]?.click(); - return; - } if (event.key === "Enter") { const highlighted = rows.find((row) => row.hasAttribute("data-chat-model-highlighted")); if (highlighted) { @@ -258,6 +253,16 @@ function handleModelSearchKeydown(event: KeyboardEvent): void { rows[nextIndex]?.scrollIntoView?.({ block: "nearest" }); } +function handleModelPickerKeydown(event: KeyboardEvent): void { + const details = event.currentTarget as HTMLDetailsElement; + if (!details.open || event.target instanceof HTMLInputElement || !/^[1-9]$/u.test(event.key)) { + return; + } + const row = visibleModelRows(details)[Number(event.key) - 1]; + event.preventDefault(); + row?.click(); +} + function renderCatalogState(state: ChatModelCatalogState | undefined, hasOptions: boolean) { if (!state || (state.status === "ready" && hasOptions)) { return nothing; @@ -382,6 +387,7 @@ export function renderChatModelPicker(params: ChatModelPickerParams) { return html`
{ const details = event.currentTarget as HTMLDetailsElement; if (!details.open) { @@ -392,7 +398,6 @@ export function renderChatModelPicker(params: ChatModelPickerParams) { const input = details.querySelector("[data-chat-model-search]"); if (input) { updateModelSearch(input); - input.focus({ preventScroll: true }); } }); }} @@ -411,7 +416,9 @@ export function renderChatModelPicker(params: ChatModelPickerParams) { @click=${(event: MouseEvent) => { if (params.disabled) { event.preventDefault(); + return; } + (event.currentTarget as HTMLElement).focus({ preventScroll: true }); }} > ${modelToolsUnavailable diff --git a/ui/src/styles/chat/layout.css b/ui/src/styles/chat/layout.css index 0f59e3c6d447..c5a970cd7c9c 100644 --- a/ui/src/styles/chat/layout.css +++ b/ui/src/styles/chat/layout.css @@ -4587,16 +4587,17 @@ button.chat-reply-preview--message:disabled { margin-left: auto; } -.chat-controls__model-option-action kbd { - min-width: 18px; - padding: 1px 4px; - border: 1px solid color-mix(in srgb, var(--border) 72%, transparent); - border-radius: 4px; - color: var(--muted); - font-family: inherit; - font-size: 10px; - line-height: 1.35; - text-align: center; +@media (prefers-reduced-motion: no-preference) { + .chat-controls__model-option-action kbd { + transition: opacity var(--duration-fast) var(--ease-out); + } +} + +.chat-controls__model-search-wrap:focus-within + ~ .chat-controls__model-options + .chat-controls__model-option-action + kbd { + opacity: 0; } .chat-controls__model-option-action kbd::before { diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css index 2b22bf145cec..a93668fe5403 100644 --- a/ui/src/styles/layout.css +++ b/ui/src/styles/layout.css @@ -2789,7 +2789,8 @@ wa-dropdown-item.session-menu__item::part(submenu-icon) { /* Keycap hint, not content: the app's quiet mono shortcut idiom (see .chat-question-panel__option kbd), fixed-width so letters and digits share one rail beside the labels. */ -.session-menu__shortcut { +.session-menu__shortcut, +.chat-controls__model-option-action kbd { flex: 0 0 auto; min-width: 12px; color: var(--muted); From dd57cfb6c150b8201680b8e8930de0403d71856c Mon Sep 17 00:00:00 2001 From: "Vyctor H. Brzezowski" Date: Wed, 12 Aug 2026 02:18:05 -0300 Subject: [PATCH 027/165] fix(ui): show catalog labels in hidden section settings (#122320) * test(ui): reproduce hidden catalog id labels * fix(ui): label hidden session catalogs * test(ui): capture hidden catalog label evidence * test(ui): harden hidden catalog label proof --- ui/src/e2e/sidebar-customization.e2e.test.ts | 79 +++++++++++++++++++ ui/src/pages/config/config-page.ts | 46 ++++++++++- .../config/view-appearance-preferences.ts | 2 +- ui/src/pages/config/view-types.ts | 1 + ui/src/pages/config/view.browser.test.ts | 21 +++-- 5 files changed, 140 insertions(+), 9 deletions(-) diff --git a/ui/src/e2e/sidebar-customization.e2e.test.ts b/ui/src/e2e/sidebar-customization.e2e.test.ts index 3c2a2d2e6a68..62e2845bb9c4 100644 --- a/ui/src/e2e/sidebar-customization.e2e.test.ts +++ b/ui/src/e2e/sidebar-customization.e2e.test.ts @@ -20,6 +20,7 @@ const suite = createControlUiE2eSuite({ }); const captureUiProofEnabled = process.env.OPENCLAW_CAPTURE_UI_PROOF === "1"; +const hiddenSessionCatalogsStorageKey = "openclaw:sidebar:sessions:hidden-catalogs"; const uiProofArtifactDir = path.join( process.cwd(), ".artifacts", @@ -93,6 +94,19 @@ async function holdUiProof(page: Page, durationMs = 600) { } } +async function setThemeMode(page: Page, mode: "dark" | "light") { + await page.emulateMedia({ colorScheme: mode }); + await page.evaluate((nextMode) => { + const root = document.documentElement; + root.dataset.themeMode = nextMode; + root.dataset.themeResolved = nextMode; + root.classList.toggle("wa-light", nextMode === "light"); + root.classList.toggle("wa-dark", nextMode === "dark"); + root.style.colorScheme = nextMode; + }, mode); + await expect.poll(() => page.locator("html").getAttribute("data-theme-mode")).toBe(mode); +} + async function openSidebarTestPage() { const context = await suite.browser.newContext({ locale: "en-US", @@ -107,6 +121,71 @@ async function openSidebarTestPage() { } suite.define(() => { + it("uses catalog labels in the hidden-section recovery rows", async () => { + const context = await suite.browser.newContext({ + locale: "en-US", + serviceWorkers: "block", + viewport: { height: 900, width: 1440 }, + }); + const page = await context.newPage(); + await page.addInitScript(({ key, value }) => localStorage.setItem(key, JSON.stringify(value)), { + key: hiddenSessionCatalogsStorageKey, + value: ["claude", "offline-catalog"], + }); + const gateway = await installMockGateway(page, { + featureMethods: ["sessions.catalog.list"], + methodResponses: { + "sessions.catalog.list": { + catalogs: [ + { + id: "claude", + label: "Claude Code", + capabilities: { continueSession: true, archive: false }, + hosts: [], + }, + ], + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}settings/appearance`); + await waitForControlUiSettingsTakeover(page); + await gateway.waitForRequest("sessions.catalog.list"); + const sidebarSettings = page.locator("#settings-appearance-sidebar"); + await sidebarSettings.getByRole("heading", { name: "Hidden session sections" }).waitFor(); + const recovery = sidebarSettings.locator(".settings-group", { hasText: "offline-catalog" }); + const row = recovery.locator(".settings-row", { hasText: "Claude Code" }); + await expect.poll(() => recovery.textContent()).toContain("Claude Code"); + await expect.poll(() => recovery.textContent()).toContain("offline-catalog"); + expect(await recovery.getByText("claude", { exact: true }).count()).toBe(0); + + if (captureUiProofEnabled) { + await mkdir(uiProofArtifactDir, { recursive: true }); + await recovery.scrollIntoViewIfNeeded(); + for (const theme of ["light", "dark"] as const) { + await setThemeMode(page, theme); + await page.screenshot({ + animations: "disabled", + path: path.join(uiProofArtifactDir, `after-${theme}-context.png`), + }); + await recovery.screenshot({ + animations: "disabled", + path: path.join(uiProofArtifactDir, `after-${theme}-rows.png`), + }); + } + } + + await row.getByRole("button", { name: "Show" }).click(); + await expect.poll(() => row.count()).toBe(0); + expect( + await page.evaluate((key) => localStorage.getItem(key), hiddenSessionCatalogsStorageKey), + ).toBe('["offline-catalog"]'); + } finally { + await context.close(); + } + }); + it("pins routes, restores defaults, and persists navigation state across reloads", async () => { if (captureUiProofEnabled) { await mkdir(uiProofArtifactDir, { recursive: true }); diff --git a/ui/src/pages/config/config-page.ts b/ui/src/pages/config/config-page.ts index dc4e8eb2f3da..e6c0cf7438bc 100644 --- a/ui/src/pages/config/config-page.ts +++ b/ui/src/pages/config/config-page.ts @@ -4,7 +4,10 @@ import { initialState, Task, TaskStatus } from "@lit/task"; import { asNullableRecord as asConfigRecord } from "@openclaw/normalization-core/record-coerce"; import { html, nothing, type PropertyValues } from "lit"; import { property, state } from "lit/decorators.js"; -import type { SystemInfoResult } from "../../../../packages/gateway-protocol/src/index.js"; +import type { + SessionsCatalogListResult, + SystemInfoResult, +} from "../../../../packages/gateway-protocol/src/index.js"; import type { GatewayBrowserClient } from "../../api/gateway.ts"; import type { ModelCatalogEntry } from "../../api/types.ts"; import { titleForRoute } from "../../app-navigation.ts"; @@ -114,6 +117,7 @@ const MOVED_SECTION_ROUTES: Record = new Map(); function defaultConfigSelection(pageId: ConfigPageId): ConfigSelection { switch (pageId) { @@ -338,6 +342,42 @@ export class ConfigPage extends OpenClawLightDomElement { } }, }); + private readonly hiddenSessionCatalogLabelsTask = new Task(this, { + args: () => { + const gateway = this.context?.gateway.snapshot; + const hiddenCatalogIds = [...this.hiddenSessionCatalogIds].toSorted(); + const client = + this.pageId === "appearance" && + hiddenCatalogIds.length > 0 && + canCallGatewayMethod(gateway, "sessions.catalog.list", "operator.read") + ? gateway?.client + : null; + return [ + client, + this.context?.agentSelection.state.selectedId ?? null, + hiddenCatalogIds.join("\0"), + ] as const; + }, + task: async ([client, agentId], { signal }) => { + if (!client) { + return EMPTY_SESSION_CATALOG_LABELS; + } + try { + const result = await client.request( + "sessions.catalog.list", + { + ...(agentId ? { agentId } : {}), + limitPerHost: 1, + }, + { signal }, + ); + return new Map(result.catalogs.map((catalog) => [catalog.id, catalog.label])); + } catch { + // Recovery must remain available when catalog discovery is unsupported or offline. + return EMPTY_SESSION_CATALOG_LABELS; + } + }, + }); private pendingRouteTargetId: string | null = null; private readonly subscriptions = new SubscriptionsController(this) .watch( @@ -1170,6 +1210,10 @@ export class ConfigPage extends OpenClawLightDomElement { this.settings.sidebarLiveActivity ?? UI_APPEARANCE_DEFAULTS.sidebarLiveActivity, setSidebarLiveActivity: (enabled) => this.setSetting("sidebarLiveActivity", enabled), hiddenSessionCatalogIds: this.hiddenSessionCatalogIds, + hiddenSessionCatalogLabels: + this.hiddenSessionCatalogLabelsTask.status === TaskStatus.COMPLETE + ? (this.hiddenSessionCatalogLabelsTask.value ?? EMPTY_SESSION_CATALOG_LABELS) + : EMPTY_SESSION_CATALOG_LABELS, setSessionCatalogHidden: setStoredSessionCatalogHidden, chatMessageMaxWidth: this.settings.chatMessageMaxWidth, setChatMessageMaxWidth: (value) => this.setSetting("chatMessageMaxWidth", value), diff --git a/ui/src/pages/config/view-appearance-preferences.ts b/ui/src/pages/config/view-appearance-preferences.ts index 7100e66e4842..ab931478f78e 100644 --- a/ui/src/pages/config/view-appearance-preferences.ts +++ b/ui/src/pages/config/view-appearance-preferences.ts @@ -486,7 +486,7 @@ export function renderSidebarPreferencesSection(props: ConfigProps) {
${hiddenCatalogIds.map((catalogId) => renderSettingsRow({ - title: catalogId, + title: props.hiddenSessionCatalogLabels.get(catalogId) ?? catalogId, description: t("quickSettings.personal.browserOnly"), control: html` + ` + : nothing; const desktopPanelAction = desktopPanelAvailable ? html` - - ` - : nothing; - const browserButton = sessionWorkspace.onToggleBrowser - ? html` - - - - ` - : nothing; - const custodianButton = sessionWorkspace.onToggleCustodian - ? html` - - - - ` - : nothing; - const diffButton = sessionWorkspace.onOpenDiff - ? html` - - - - ` - : nothing; const files = sessionWorkspace.list?.files ?? []; const modifiedFiles = files.filter((file) => file.kind === "modified"); const readFiles = files.filter((file) => file.kind === "read"); @@ -1306,7 +1244,6 @@ export function renderSessionWorkspaceRail( ${t("chat.workspaceFiles.files")}
- ${diffButton} ${terminalButton} ${browserButton} ${custodianButton} ${sessionWorkspace.narrowLayout ? nothing : html` diff --git a/ui/src/styles/chat/sidebar.css b/ui/src/styles/chat/sidebar.css index 6370835c8ce2..92ad14b082e9 100644 --- a/ui/src/styles/chat/sidebar.css +++ b/ui/src/styles/chat/sidebar.css @@ -454,7 +454,6 @@ openclaw-chat-sidebar-region, gap: 6px; } -.chat-workspace-rail__terminal, .chat-workspace-rail__refresh, .chat-workspace-rail__dock, .chat-workspace-rail__collapse-toggle { @@ -476,24 +475,6 @@ openclaw-chat-sidebar-region, cursor: grabbing; } -.chat-workspace-rail__terminal { - display: inline-flex; - align-items: center; - justify-content: center; - /* Chromeless at rest like the sibling ghost buttons; chrome on hover only. */ - border: 1px solid transparent; - border-radius: var(--radius-md); - background: transparent; - color: var(--muted); -} - -.chat-workspace-rail__terminal:hover, -.chat-workspace-rail__terminal:focus-visible { - color: var(--text); - border-color: color-mix(in srgb, var(--accent) 34%, var(--border)); - background: color-mix(in srgb, var(--accent) 8%, transparent); -} - /* Overrides the shared .nav-collapse-toggle chrome (border, elevated background, inset highlight): rail header buttons only show chrome on hover. */ @@ -510,7 +491,6 @@ openclaw-chat-sidebar-region, transform: none; } -.chat-workspace-rail__terminal svg, .chat-workspace-rail__refresh svg, .chat-workspace-rail__dock svg, .chat-workspace-rail__collapse-toggle svg, From 83bca6844025c545a93cdf42c569f64fc43665d3 Mon Sep 17 00:00:00 2001 From: Ayaan Zaidi Date: Wed, 12 Aug 2026 12:44:46 +0530 Subject: [PATCH 054/165] fix: remove new-chat startup stalls (#122471) * fix(gateway): defer dashboard title generation * perf(agents): reuse prepared plugin metadata for model catalogs * perf(agents): keep live model inventory off turn startup * perf: keep isolated completions on static catalogs * fix: preserve fast readable worktree names * refactor: remove unnecessary title startup plumbing --- src/agents/agent-model-discovery.test.ts | 4 +- .../embedded-agent-runner/run-orchestrator.ts | 6 +- .../usage-reporting.test-support.ts | 2 +- src/agents/isolated-completion.test.ts | 3 + src/agents/isolated-completion.ts | 35 +++-- src/gateway/dashboard-session-title.test.ts | 112 +++---------- src/gateway/dashboard-session-title.ts | 4 +- .../chat-send-agent-dispatch.ts | 22 ++- .../server-methods/chat-send-handler.ts | 14 -- src/gateway/server-methods/sessions-create.ts | 54 +------ src/gateway/server.sessions.create.test.ts | 147 ++++++++++++++---- 11 files changed, 194 insertions(+), 209 deletions(-) diff --git a/src/agents/agent-model-discovery.test.ts b/src/agents/agent-model-discovery.test.ts index 7afdce937dae..797c32aad279 100644 --- a/src/agents/agent-model-discovery.test.ts +++ b/src/agents/agent-model-discovery.test.ts @@ -20,9 +20,7 @@ beforeEach(() => { clearCurrentPluginMetadataSnapshot(); }); -afterEach(() => { - vi.unstubAllEnvs(); -}); +afterEach(() => vi.unstubAllEnvs()); function writeModelsJson(agentDir: string, modelId: string): void { fs.writeFileSync( diff --git a/src/agents/embedded-agent-runner/run-orchestrator.ts b/src/agents/embedded-agent-runner/run-orchestrator.ts index 9df2d0e6d305..98519a1e6ddb 100644 --- a/src/agents/embedded-agent-runner/run-orchestrator.ts +++ b/src/agents/embedded-agent-runner/run-orchestrator.ts @@ -268,9 +268,9 @@ async function runEmbeddedAgentInternal( ? acquireReadOnlyPreparedModelRuntime(preparedInput) : acquireAgentRunPreparedModelRuntime(preparedInput, { retainIdleRunOwner, - // A one-shot turn needs only configured turn-admission facts. Full live model - // inventory remains available through the snapshot's lazy control-plane loader. - ...(params.oneShotCliRun ? { catalogMode: "static" } : {}), + // Turns need only configured admission facts. Full live model inventory remains + // available through the snapshot's lazy control-plane loader. + catalogMode: "static", }), ); startupStages.mark("prepared-runtime"); diff --git a/src/agents/embedded-agent-runner/usage-reporting.test-support.ts b/src/agents/embedded-agent-runner/usage-reporting.test-support.ts index bc52b51e5472..5056a737e730 100644 --- a/src/agents/embedded-agent-runner/usage-reporting.test-support.ts +++ b/src/agents/embedded-agent-runner/usage-reporting.test-support.ts @@ -87,7 +87,7 @@ describe("runEmbeddedAgent usage reporting", () => { expect.objectContaining({ provider: "openai", modelId: "gpt-5.5" }), ]), }), - expect.anything(), + expect.objectContaining({ catalogMode: "static" }), ); }); diff --git a/src/agents/isolated-completion.test.ts b/src/agents/isolated-completion.test.ts index ffe5a42813b6..f1b385481710 100644 --- a/src/agents/isolated-completion.test.ts +++ b/src/agents/isolated-completion.test.ts @@ -196,6 +196,9 @@ describe("runIsolatedCompletion", () => { text: "native result", owner: { kind: "harness", id: "codex" }, }); + expect(mocks.acquireAgentRunPreparedModelRuntime).toHaveBeenCalledWith(expect.any(Object), { + catalogMode: "static", + }); expect(mocks.prepareSimpleCompletionModel).not.toHaveBeenCalled(); expect(runIsolatedCompletionV2).toHaveBeenCalledWith( expect.objectContaining({ diff --git a/src/agents/isolated-completion.ts b/src/agents/isolated-completion.ts index 0fbf2f3be461..1fff7c9aac06 100644 --- a/src/agents/isolated-completion.ts +++ b/src/agents/isolated-completion.ts @@ -436,22 +436,25 @@ export async function runIsolatedCompletion( config, includeSetupRegistry: true, }) ?? request.provider; - const lease = await acquireAgentRunPreparedModelRuntime({ - config, - agentId, - agentDir, - workspaceDir, - runtimePluginSelections: [ - { - provider, - modelId: request.model, - ...(request.agentHarnessRuntimeOverride - ? { runtime: request.agentHarnessRuntimeOverride } - : {}), - agentId, - }, - ], - }); + const lease = await acquireAgentRunPreparedModelRuntime( + { + config, + agentId, + agentDir, + workspaceDir, + runtimePluginSelections: [ + { + provider, + modelId: request.model, + ...(request.agentHarnessRuntimeOverride + ? { runtime: request.agentHarnessRuntimeOverride } + : {}), + agentId, + }, + ], + }, + { catalogMode: "static" }, + ); const pluginRegistry = lease.snapshot.pluginRegistry; try { const run = async (): Promise => { diff --git a/src/gateway/dashboard-session-title.test.ts b/src/gateway/dashboard-session-title.test.ts index 270e2accfd4a..6be4c1f32314 100644 --- a/src/gateway/dashboard-session-title.test.ts +++ b/src/gateway/dashboard-session-title.test.ts @@ -17,7 +17,7 @@ import type { SessionEntry } from "../config/sessions/types.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; import type { ChatAttachment } from "./chat-attachments.js"; import { - generateDashboardSessionTitle, + buildDashboardSessionTitleSource, maybeGenerateDashboardSessionTitle, } from "./dashboard-session-title.js"; @@ -334,51 +334,26 @@ describe("maybeGenerateDashboardSessionTitle", () => { }); }); -describe("generateDashboardSessionTitle", () => { - beforeEach(() => { - generateConversationLabelWithFallback.mockReset(); - resolveUtilityModelRefForAgent.mockReset(); - generateConversationLabelWithFallback.mockResolvedValue("Worktree Naming Improvements"); - resolveUtilityModelRefForAgent.mockReturnValue("openai/gpt-5.6-luna"); - }); - - it("generates the reusable short dashboard title", async () => { - await expect( - generateDashboardSessionTitle({ - cfg, - agentId: "main", - userMessage: "Please improve the default names for managed worktrees", - }), - ).resolves.toBe("Worktree Naming Improvements"); - }); - +describe("buildDashboardSessionTitleSource", () => { it("combines an ordinary command with large pasted text within the title-source cap", async () => { const pastedText = `Release details ${"x".repeat(2_000)}`; - - await generateDashboardSessionTitle({ - cfg, - agentId: "main", - userMessage: "Review this rollout [[reply_to_current]]", + const source = buildDashboardSessionTitleSource({ + message: "Review this rollout [[reply_to_current]]", attachments: [textAttachment("Deployment context"), textAttachment(pastedText)], }); - - expect(generateConversationLabelWithFallback.mock.calls[0]?.[0]?.userMessage).toBe( - `Review this rollout\nDeployment context\n${pastedText}`.slice(0, 1_000), - ); + expect(source).toBe(`Review this rollout\nDeployment context\n${pastedText}`.slice(0, 1_000)); }); it.each([ ["attachment-only", "", "Pasted migration checklist"], ["slash command with attachment", "/status", "Pasted incident report"], ])("titles an %s turn from its text attachment", async (_name, userMessage, text) => { - await generateDashboardSessionTitle({ - cfg, - agentId: "main", - userMessage, - attachments: [textAttachment(text)], - }); - - expect(generateConversationLabelWithFallback.mock.calls[0]?.[0]?.userMessage).toBe(text); + expect( + buildDashboardSessionTitleSource({ + message: userMessage, + attachments: [textAttachment(text)], + }), + ).toBe(text); }); it.each([ @@ -390,72 +365,29 @@ describe("generateDashboardSessionTitle", () => { ["non-text", { mimeType: "image/png", content: Buffer.from("not text").toString("base64") }], ] satisfies Array<[string, ChatAttachment]>)( "ignores %s attachments", - async (_name, attachment) => { - await expect( - generateDashboardSessionTitle({ - cfg, - agentId: "main", - userMessage: "", - attachments: [attachment], - }), - ).resolves.toBeNull(); - expect(generateConversationLabelWithFallback).not.toHaveBeenCalled(); - }, + async (_name, attachment) => + expect(buildDashboardSessionTitleSource({ message: "", attachments: [attachment] })).toBe(""), ); it("ignores a long text attachment with malformed trailing base64", async () => { const valid = Buffer.from("a".repeat(4_000)).toString("base64"); const malformed = `${valid.slice(0, -4)}AAA%`; - await expect( - generateDashboardSessionTitle({ - cfg, - agentId: "main", - userMessage: "", + expect( + buildDashboardSessionTitleSource({ + message: "", attachments: [{ mimeType: "text/plain", content: malformed }], }), - ).resolves.toBeNull(); - expect(generateConversationLabelWithFallback).not.toHaveBeenCalled(); + ).toBe(""); }); it("keeps attachment-derived title input on a UTF-16 boundary", async () => { - await generateDashboardSessionTitle({ - cfg, - agentId: "main", - userMessage: "", - attachments: [textAttachment(`${"a".repeat(999)}🚀tail`)], - }); - - expect(generateConversationLabelWithFallback.mock.calls[0]?.[0]?.userMessage).toBe( - "a".repeat(999), - ); - }); - - it("uses a requested session model as the primary fallback", async () => { - await generateDashboardSessionTitle({ - cfg, - agentId: "main", - entry: { - providerOverride: "anthropic", - modelOverride: "claude-opus-4-5", - authProfileOverride: "work", - }, - userMessage: "Please improve the default names for managed worktrees", - }); - - expect(generateConversationLabelWithFallback).toHaveBeenCalledWith( - expect.objectContaining({ - regularModelRef: "anthropic/claude-opus-4-5@work", - preferredProfile: "work", + expect( + buildDashboardSessionTitleSource({ + message: "", + attachments: [textAttachment(`${"a".repeat(999)}🚀tail`)], }), - ); - }); - - it.each(["", " ", "/status"])("skips non-title prompt %j", async (userMessage) => { - await expect( - generateDashboardSessionTitle({ cfg, agentId: "main", userMessage }), - ).resolves.toBeNull(); - expect(generateConversationLabelWithFallback).not.toHaveBeenCalled(); + ).toBe("a".repeat(999)); }); }); diff --git a/src/gateway/dashboard-session-title.ts b/src/gateway/dashboard-session-title.ts index 4311d2fe0a48..04721edb8ec1 100644 --- a/src/gateway/dashboard-session-title.ts +++ b/src/gateway/dashboard-session-title.ts @@ -1,5 +1,4 @@ import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice"; -// Dashboard session titles use the shared utility-model completion path. import { resolveAgentEffectiveModelPrimary } from "../agents/agent-scope.js"; import { splitTrailingAuthProfile } from "../agents/model-ref-profile.js"; import { resolveSessionModelRef } from "../agents/session-model-ref.js"; @@ -155,8 +154,7 @@ function normalizeDashboardSessionTitle(raw: string): string | null { return normalized ? truncateUtf16Safe(normalized, DASHBOARD_SESSION_TITLE_MAX_CHARS) : null; } -/** Generates the same short title used by dashboard session rows without persisting it. */ -export async function generateDashboardSessionTitle(params: { +async function generateDashboardSessionTitle(params: { cfg: OpenClawConfig; agentId: string; entry?: DashboardSessionTitleModelEntry; diff --git a/src/gateway/server-methods/chat-send-agent-dispatch.ts b/src/gateway/server-methods/chat-send-agent-dispatch.ts index a29d90d7ca5b..d43a750dcff0 100644 --- a/src/gateway/server-methods/chat-send-agent-dispatch.ts +++ b/src/gateway/server-methods/chat-send-agent-dispatch.ts @@ -18,7 +18,10 @@ import type { ChatRunTiming } from "../server-chat-state.js"; import { broadcastChatError, broadcastChatFinal } from "./chat-broadcast.js"; import type { AdmittedChatSend } from "./chat-send-admission.js"; import type { prepareChatSendAttachments } from "./chat-send-attachments.js"; -import { resolveWebchatPromptCacheKey } from "./chat-send-background.js"; +import { + resolveWebchatPromptCacheKey, + scheduleChatDashboardSessionTitle, +} from "./chat-send-background.js"; import { createChatSendDispatchErrorLifecycle } from "./chat-send-dispatch-errors.js"; import type { ChatSendExternalAuthorityAdmission } from "./chat-send-external-authority-contract.js"; import { finalizeAcceptedChatSendMessageInjection } from "./chat-send-message-injection.js"; @@ -503,5 +506,20 @@ export function startChatDispatch(params: StartChatDispatchParams): void { } }) .catch(dispatchErrorLifecycle.handleError) - .finally(dispatchErrorLifecycle.finalize); + .finally(() => { + dispatchErrorLifecycle.finalize(); + // Cosmetic title work starts only after the accepted turn finishes. Starting it + // before dispatch can make a cold utility runtime starve the user's real turn. + scheduleChatDashboardSessionTitle({ + admittedSessionId, + agentId, + cfg, + context, + entry, + request, + sessionKey, + sessionLoadOptions: session.sessionLoadOptions, + storePath: session.storePath, + }); + }); } diff --git a/src/gateway/server-methods/chat-send-handler.ts b/src/gateway/server-methods/chat-send-handler.ts index cfc02b237f06..06de56863696 100644 --- a/src/gateway/server-methods/chat-send-handler.ts +++ b/src/gateway/server-methods/chat-send-handler.ts @@ -7,7 +7,6 @@ import type { ChatRunTiming } from "../server-chat-state.js"; import { terminalizeRestartSafeChatAdmission } from "./chat-restart-recovery.js"; import { startChatDispatch } from "./chat-send-agent-dispatch.js"; import { prepareChatSendAttachments } from "./chat-send-attachments.js"; -import { scheduleChatDashboardSessionTitle } from "./chat-send-background.js"; import { handleChatSendSetupError } from "./chat-send-dispatch-errors.js"; import type { ChatSendExternalAuthorityAdmission } from "./chat-send-external-authority-contract.js"; import { @@ -42,7 +41,6 @@ export async function handleChatSend( normalizedRequest.value; const { clientRunId, - sessionLoadOptions, sessionLoadMs, cfg, storePath, @@ -50,7 +48,6 @@ export async function handleChatSend( sessionKey, sessionRoutingChanged, selectedAgent, - agentId, } = preparedSession.value; const { activeRunAbort, @@ -250,17 +247,6 @@ export async function handleChatSend( ); respond(true, ackPayload, undefined, { runId: clientRunId }); const chatSendAckedAtMs = chatSendTiming?.ackedAtMs ?? performance.now(); - scheduleChatDashboardSessionTitle({ - admittedSessionId, - agentId, - cfg, - context, - entry, - request: normalizedRequest.value, - sessionKey, - sessionLoadOptions, - storePath, - }); startChatDispatch({ admissionStartedAt, admission: admitted.value, diff --git a/src/gateway/server-methods/sessions-create.ts b/src/gateway/server-methods/sessions-create.ts index e5167ce1196b..3faf2a445601 100644 --- a/src/gateway/server-methods/sessions-create.ts +++ b/src/gateway/server-methods/sessions-create.ts @@ -12,14 +12,12 @@ import { validateSessionsCreateParams, } from "../../../packages/gateway-protocol/src/index.js"; import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js"; -import { resolveDefaultModelForAgent } from "../../agents/model-selection.js"; import { resolveSandboxRuntimeStatus } from "../../agents/sandbox/runtime-status.js"; import { insideGitCheckout } from "../../agents/worktrees/git.js"; import { slugifyWorktreeTitle } from "../../agents/worktrees/name.js"; import { managedWorktrees, WorktreeRepositoryError } from "../../agents/worktrees/service.js"; import { resolveAgentMainSessionKey } from "../../config/sessions/main-session.js"; import { sessionEntryForkedFromParent } from "../../config/sessions/session-entry-lineage.js"; -import type { SessionEntry } from "../../config/sessions/types.js"; import { formatErrorMessage } from "../../infra/errors.js"; import { isPathInside } from "../../infra/path-guards.js"; import { @@ -29,7 +27,7 @@ import { } from "../../projects/project-registry.js"; import { normalizeAgentId, parseAgentSessionKey } from "../../routing/session-key.js"; import { resolveUserPath } from "../../utils.js"; -import { generateDashboardSessionTitle } from "../dashboard-session-title.js"; +import { buildDashboardSessionTitleSource } from "../dashboard-session-title.js"; import { ADMIN_SCOPE, authorizeOperatorScopesForRequiredScope } from "../method-scopes.js"; import { buildDashboardSessionKey, createGatewaySession } from "../session-create-service.js"; import type { PrepareGatewaySessionLifecycle } from "../session-lifecycle-preparation.js"; @@ -40,7 +38,6 @@ import { loadGatewaySessionEntryReadOnly, resolveGatewaySessionStoreTarget, } from "../session-utils.js"; -import { resolveSessionPatchModelSelection } from "../sessions-patch.js"; import { createAgentRuntimeAuthorityGuard } from "./agent-runtime-authority.js"; import { chatHandlers } from "./chat.js"; import { resolveRegisteredCatalogCreateTarget } from "./session-catalog.js"; @@ -231,7 +228,6 @@ export const sessionCreateHandlers: GatewayRequestHandlers = { const sessionExecCwd = requestedExecNode ? requestedCwd : undefined; let sessionCwd = requestedExecNode ? undefined : (projectRoot ?? requestedCwd); let prepareLifecycle: PrepareGatewaySessionLifecycle | undefined; - let generatedDisplayName: string | undefined; if (sessionCwd && !requestedExecNode && (requestedProjectId || p.worktree !== true)) { const targetAgentId = normalizeAgentId( sessionAgentId ?? @@ -338,47 +334,6 @@ export const sessionCreateHandlers: GatewayRequestHandlers = { return; } - if ( - !requestedWorktreeName && - !normalizeOptionalString(p.label) && - (initialMessage || initialAttachments) - ) { - try { - const requestedTitleModel = - catalogTarget?.target.model ?? normalizeOptionalString(p.model); - let titleModelEntry: - | Pick - | undefined; - if (requestedTitleModel) { - const defaultModel = resolveDefaultModelForAgent({ cfg, agentId: target.agentId }); - const selection = resolveSessionPatchModelSelection({ - cfg, - catalog: await context.loadGatewayModelCatalog({ agentId: target.agentId }), - raw: requestedTitleModel, - defaultProvider: defaultModel.provider, - defaultModel: defaultModel.model, - }); - if (selection.ok) { - titleModelEntry = { - providerOverride: selection.provider, - modelOverride: selection.model, - ...(selection.profile ? { authProfileOverride: selection.profile } : {}), - }; - } - } - generatedDisplayName = - (await generateDashboardSessionTitle({ - cfg, - agentId: target.agentId, - entry: titleModelEntry, - userMessage: initialMessage ?? "", - attachments: initialAttachments, - })) ?? undefined; - } catch (error) { - sessionLog.warn(`worktree title generation failed: ${formatErrorMessage(error)}`); - } - } - const scopes = Array.isArray(client?.connect.scopes) ? client.connect.scopes : []; prepareLifecycle = async (lifecycleTarget) => { try { @@ -430,7 +385,11 @@ export const sessionCreateHandlers: GatewayRequestHandlers = { ownerId: lifecycleTarget.key, name: requestedWorktreeName, suggestedName: slugifyWorktreeTitle( - normalizeOptionalString(p.label) ?? generatedDisplayName ?? "", + normalizeOptionalString(p.label) ?? + buildDashboardSessionTitleSource({ + message: initialMessage ?? "", + attachments: initialAttachments, + }), ), baseRef: requestedWorktreeBaseRef, // Checkout hooks and .openclaw/worktree-setup.sh run repo code; keep them @@ -525,7 +484,6 @@ export const sessionCreateHandlers: GatewayRequestHandlers = { key: sessionKey, agentId: sessionAgentId, label: p.label, - generatedDisplayName, ...(catalogTarget ? { catalogTarget: catalogTarget.target } : { model: p.model }), thinkingLevel: p.thinkingLevel, projectId: requestedProjectId, diff --git a/src/gateway/server.sessions.create.test.ts b/src/gateway/server.sessions.create.test.ts index 15dffa6a28fa..399ed2d1d44c 100644 --- a/src/gateway/server.sessions.create.test.ts +++ b/src/gateway/server.sessions.create.test.ts @@ -62,8 +62,10 @@ import { type EnsureSessionDiffBaseline = (typeof import("../sessions/session-diff-baseline.js"))["ensureSessionDiffBaseline"]; -type GenerateDashboardSessionTitle = - (typeof import("./dashboard-session-title.js"))["generateDashboardSessionTitle"]; +type GenerateConversationLabelWithFallback = + (typeof import("../auto-reply/reply/conversation-label-generator.js"))["generateConversationLabelWithFallback"]; +type ScheduleChatDashboardSessionTitle = + (typeof import("./server-methods/chat-send-background.js"))["scheduleChatDashboardSessionTitle"]; type ReadSessionMessageCountAsync = (typeof import("./session-transcript-readers.js"))["readSessionMessageCountAsync"]; @@ -72,9 +74,14 @@ const sessionDiffBaselineMocks = vi.hoisted(() => ({ useReal: false, })); -const dashboardTitleMocks = vi.hoisted(() => ({ - actual: undefined as GenerateDashboardSessionTitle | undefined, - generate: vi.fn(), +const dashboardTitleGenerationMocks = vi.hoisted(() => ({ + actual: undefined as GenerateConversationLabelWithFallback | undefined, + generate: vi.fn(), +})); + +const dashboardTitleScheduleMocks = vi.hoisted(() => ({ + actual: undefined as ScheduleChatDashboardSessionTitle | undefined, + schedule: vi.fn(), })); const sessionTranscriptReaderMocks = vi.hoisted(() => ({ @@ -92,11 +99,24 @@ vi.mock("../sessions/session-diff-baseline.js", async (importOriginal) => { return { ...actual, ensureSessionDiffBaseline: sessionDiffBaselineMocks.ensure }; }); -vi.mock("./dashboard-session-title.js", async (importOriginal) => { - const actual = await importOriginal(); - dashboardTitleMocks.actual = actual.generateDashboardSessionTitle; - dashboardTitleMocks.generate.mockImplementation(actual.generateDashboardSessionTitle); - return { ...actual, generateDashboardSessionTitle: dashboardTitleMocks.generate }; +vi.mock("../auto-reply/reply/conversation-label-generator.js", async (importOriginal) => { + const actual = + await importOriginal(); + dashboardTitleGenerationMocks.actual = actual.generateConversationLabelWithFallback; + dashboardTitleGenerationMocks.generate.mockImplementation( + actual.generateConversationLabelWithFallback, + ); + return { + ...actual, + generateConversationLabelWithFallback: dashboardTitleGenerationMocks.generate, + }; +}); + +vi.mock("./server-methods/chat-send-background.js", async (importOriginal) => { + const actual = await importOriginal(); + dashboardTitleScheduleMocks.actual = actual.scheduleChatDashboardSessionTitle; + dashboardTitleScheduleMocks.schedule.mockImplementation(actual.scheduleChatDashboardSessionTitle); + return { ...actual, scheduleChatDashboardSessionTitle: dashboardTitleScheduleMocks.schedule }; }); vi.mock("./session-transcript-readers.js", async (importOriginal) => { @@ -115,11 +135,16 @@ beforeEach(() => { sessionDiffBaselineMocks.ensure.mockClear(); // Baseline capture has dedicated owner coverage and one authenticated integration below. sessionDiffBaselineMocks.useReal = false; - dashboardTitleMocks.generate.mockReset(); - if (!dashboardTitleMocks.actual) { + dashboardTitleGenerationMocks.generate.mockReset(); + if (!dashboardTitleGenerationMocks.actual) { throw new Error("actual dashboard title generator was not loaded"); } - dashboardTitleMocks.generate.mockImplementation(dashboardTitleMocks.actual); + dashboardTitleGenerationMocks.generate.mockImplementation(dashboardTitleGenerationMocks.actual); + dashboardTitleScheduleMocks.schedule.mockReset(); + if (!dashboardTitleScheduleMocks.actual) { + throw new Error("actual dashboard title scheduler was not loaded"); + } + dashboardTitleScheduleMocks.schedule.mockImplementation(dashboardTitleScheduleMocks.actual); sessionTranscriptReaderMocks.readCount.mockReset(); if (!sessionTranscriptReaderMocks.actual) { throw new Error("actual session transcript reader was not loaded"); @@ -684,6 +709,53 @@ test("createGatewaySession persists a generated title only for a new session", a expect(reused).toMatchObject({ ok: true, entry: { displayName: "Readable Worktree Names" } }); }); +test("chat.send generates a dashboard title only after the user turn finishes", async () => { + await createSessionStoreDir(); + const { ws } = await openClient(); + let finishDispatch: (() => void) | undefined; + const dispatchFinished = new Promise((resolve) => { + finishDispatch = resolve; + }); + dispatchInboundMessageMock.mockImplementationOnce(async () => { + await dispatchFinished; + return { + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }; + }); + try { + const created = await rpcReq<{ key: string }>(ws, "sessions.create", { + agentId: "main", + key: "agent:main:dashboard:title-order", + }); + expect(created.ok, JSON.stringify(created.error)).toBe(true); + const sessionKey = requireNonEmptyString(created.payload?.key, "created session key"); + + const sent = await rpcReq(ws, "chat.send", { + sessionKey, + message: "Help me plan the release", + idempotencyKey: "post-dispatch-dashboard-title", + }); + expect(sent.ok, JSON.stringify(sent.error)).toBe(true); + await waitForFast(() => expect(dispatchInboundMessageMock).toHaveBeenCalled()); + expect(dashboardTitleScheduleMocks.schedule).not.toHaveBeenCalled(); + + finishDispatch?.(); + await waitForFast(() => expect(dashboardTitleScheduleMocks.schedule).toHaveBeenCalled(), { + timeout: 5_000, + }); + expect(dashboardTitleScheduleMocks.schedule).toHaveBeenCalledWith( + expect.objectContaining({ + request: expect.objectContaining({ rawMessage: "Help me plan the release" }), + sessionKey, + }), + ); + } finally { + finishDispatch?.(); + ws.close(); + } +}); + test("incognito operator RPCs treat identityless connections as owner-equivalent", async () => { const { dir } = await createSessionStoreDir(); const admin = await openClient({ @@ -1243,7 +1315,7 @@ test("sessions.create preserves a committed worktree when initial-turn setup fai } }); -test("sessions.create derives its managed-worktree title from message and pasted text", async () => { +test("sessions.create names its managed worktree without waiting for the model title", async () => { const openClawState = await createOpenClawTestState({ layout: "state-only", prefix: "openclaw-session-worktree-title-", @@ -1261,28 +1333,45 @@ test("sessions.create derives its managed-worktree title from message and pasted mimeType: "text/plain", content: Buffer.from(pastedText).toString("base64"), }; - dashboardTitleMocks.generate.mockResolvedValueOnce("Attachment Repair"); + let resolveTitle: ((title: string) => void) | undefined; + dashboardTitleGenerationMocks.generate.mockReturnValueOnce( + new Promise((resolve) => { + resolveTitle = resolve; + }), + ); + dispatchInboundMessageMock.mockResolvedValueOnce({ + queuedFinal: false, + counts: { block: 0, final: 0, tool: 0 }, + }); + const createResult = rpcReq<{ + key: string; + worktree: { id: string; branch: string }; + }>(ws, "sessions.create", { + agentId: "main", + worktree: true, + message, + attachments: [attachment], + }); + let createSettled = false; + void createResult.then(() => { + createSettled = true; + }); try { - const created = await rpcReq<{ - worktree: { id: string; branch: string }; - }>(ws, "sessions.create", { - agentId: "main", - worktree: true, - message, - attachments: [attachment], + await waitForFast(() => expect(createSettled).toBe(true), { + timeout: 1_000, }); + const created = await createResult; expect(created.ok, JSON.stringify(created.error)).toBe(true); worktreeId = created.payload?.worktree.id; - expect(created.payload?.worktree.branch).toBe("openclaw/attachment-repair"); - expect(dashboardTitleMocks.generate).toHaveBeenCalledWith( - expect.objectContaining({ - agentId: "main", - userMessage: message, - attachments: [attachment], - }), + expect(created.payload?.worktree.branch).toBe( + "openclaw/review-this-rollout-pasted-deployment-plan-xxxxxxxxxxxxxxxxxxxxx", ); + resolveTitle?.("Attachment Repair"); } finally { + resolveTitle?.("Attachment Repair"); + const created = await createResult; + worktreeId ??= created.payload?.worktree.id; if (worktreeId) { await managedWorktrees.remove({ id: worktreeId, reason: "test-cleanup", force: true }); } From fc0147b529fb982ea8b50e3b7d657ca7aeafc508 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:19:22 -0700 Subject: [PATCH 055/165] test(plugins): remove duplicate setup cases (#122515) --- extensions/codex/harness.test.ts | 7 ----- extensions/whatsapp/src/setup-surface.test.ts | 31 ------------------- 2 files changed, 38 deletions(-) diff --git a/extensions/codex/harness.test.ts b/extensions/codex/harness.test.ts index 14a67bf257fb..dcf46e643cfe 100644 --- a/extensions/codex/harness.test.ts +++ b/extensions/codex/harness.test.ts @@ -179,13 +179,6 @@ describe("Codex agent harness supports()", () => { }); }); - it("supports the canonical openai routing id (documented Codex path)", () => { - expect(harness.supports({ provider: "openai", requestedRuntime: "codex" })).toEqual({ - supported: true, - priority: 100, - }); - }); - it("supports an official route declared compatible with Codex", () => { expect( harness.supports({ diff --git a/extensions/whatsapp/src/setup-surface.test.ts b/extensions/whatsapp/src/setup-surface.test.ts index 44a136d66d81..c414f5ac09bd 100644 --- a/extensions/whatsapp/src/setup-surface.test.ts +++ b/extensions/whatsapp/src/setup-surface.test.ts @@ -9,19 +9,16 @@ import { DEFAULT_ACCOUNT_ID, type OpenClawConfig } from "openclaw/plugin-sdk/set import { beforeEach, describe, expect, it, vi } from "vitest"; import { whatsappSetupWizard } from "./setup-surface.js"; import { - createWhatsAppAllowlistModeInput, createWhatsAppLinkingHarness, createWhatsAppOwnerAllowlistHarness, createWhatsAppPersonalPhoneHarness, createWhatsAppRootAllowFromConfig, createWhatsAppWorkAccountConfig, expectNoWhatsAppLoginFollowup, - expectWhatsAppAllowlistModeSetup, expectWhatsAppLoginFollowup, expectWhatsAppOpenPolicySetup, expectWhatsAppOwnerAllowlistSetup, expectWhatsAppPersonalPhoneSetup, - expectWhatsAppSeparatePhoneDisabledSetup, expectWhatsAppWorkAccountAccessNote, expectWhatsAppWorkAccountOpenAccess, } from "./setup-test-helpers.js"; @@ -138,20 +135,6 @@ function expectFinalizeResult(result: Awaited { beforeEach(() => { hoisted.detectWhatsAppLinked.mockReset(); @@ -186,14 +169,6 @@ describe("whatsapp setup wizard", () => { expectWhatsAppOwnerAllowlistSetup(result.cfg, harness); }); - it("supports disabled DM policy for separate-phone setup", async () => { - const { harness, result } = await runSeparatePhoneFlow({ - selectValues: ["separate", "disabled"], - }); - - expectWhatsAppSeparatePhoneDisabledSetup(result.cfg, harness); - }); - it("writes named-account DM policy and allowFrom instead of the channel root", async () => { hoisted.pathExists.mockResolvedValue(true); const harness = createSeparatePhoneHarness({ @@ -310,12 +285,6 @@ describe("whatsapp setup wizard", () => { expectWhatsAppWorkAccountAccessNote(harness); }); - it("normalizes allowFrom entries when list mode is selected", async () => { - const { result } = await runSeparatePhoneFlow(createWhatsAppAllowlistModeInput()); - - expectWhatsAppAllowlistModeSetup(result.cfg); - }); - it("enables allowlist self-chat mode for personal-phone setup", async () => { hoisted.pathExists.mockResolvedValue(true); const harness = createWhatsAppPersonalPhoneHarness(createQueuedWizardPrompter); From 0de17482ae45866d73c30af4060849a03d6c0000 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:21:23 -0700 Subject: [PATCH 056/165] feat(gateway,ui): quiet Where picker, placement chip, and projects read model (#120804) * feat(gateway): projects.list groups known checkouts by repo identity Implements docs/plan/runners.md milestone 4 derived projects read model. * feat(ui): regroup the Where picker by gateway, devices, and cloud * feat(ui): placement chip shows where a session runs with reclaim Implements docs/plan/runners.md milestone 4 placement display and reclaim. --- .../openclaw/app/gateway/GatewayProtocol.kt | 31 + .../gateway/GatewayProtocolGeneratedTest.kt | 8 + .../OpenClawProtocol/GatewayModels.swift | 64 +- .../GatewayProtocolGeneratedModelsTests.swift | 10 + .../agent-harness-runtime.json | 2 +- .../agent-harness.json | 2 +- .../plugin-sdk-api-baseline/channel-core.json | 2 +- .../channel-entry-contract.json | 2 +- .../channel-message.json | 2 +- .../channel-outbound.json | 2 +- .../channel-plugin-common.json | 2 +- .../plugin-sdk-api-baseline/core.json | 2 +- .../plugin-sdk-api-baseline/discord.json | 2 +- .../gateway-runtime.json | 2 +- .../inbound-reply-dispatch.json | 2 +- .../meeting-runtime.json | 2 +- .../plugin-sdk-api-baseline/plugin-entry.json | 2 +- .../plugin-runtime.json | 2 +- .../provider-catalog-runtime.json | 2 +- .../plugin-sdk-api-baseline/tool-plugin.json | 2 +- .../webhook-ingress.json | 2 +- docs/plan/runners.md | 57 +- packages/gateway-protocol/src/index.ts | 1 + .../src/schema/projects.test.ts | 33 + .../gateway-protocol/src/schema/projects.ts | 48 +- .../protocol-schema-fragment-agent-control.ts | 2 + scripts/protocol-gen-kotlin.ts | 1 + src/agents/worktrees/service.test.ts | 15 + src/agents/worktrees/service.ts | 21 + .../server-methods.authorization.test.ts | 28 + .../server-methods/projects-observed.test.ts | 308 +++++++ src/gateway/server-methods/projects.test.ts | 83 +- src/gateway/server-methods/projects.ts | 692 ++++++++++----- ...w-session-page.operator-scopes.e2e.test.ts | 20 +- ...w-session-page.projects-places.e2e.test.ts | 816 ++++++++++++++++++ ...sion-page.workspace-validation.e2e.test.ts | 26 + ui/src/i18n/locales/en.ts | 2 + ui/src/pages/chat/chat-pane-base.ts | 1 + ui/src/pages/chat/chat-pane-context.ts | 25 + ui/src/pages/chat/chat-pane-header.ts | 8 + ui/src/pages/chat/chat-pane-placement.test.ts | 217 +++++ ui/src/pages/chat/chat-pane-placement.ts | 102 +++ .../pages/chat/chat-pane-task-suggestions.ts | 4 +- ui/src/pages/chat/chat-pane.test-support.ts | 2 + .../chat/components/chat-pane-header.test.ts | 52 +- .../pages/chat/components/chat-pane-header.ts | 17 +- .../chat/components/chat-pane-placement.ts | 42 + .../new-session/cloud-profile-discovery.ts | 10 +- ui/src/pages/new-session/cloud-target.ts | 13 +- ui/src/pages/new-session/discovery.test.ts | 30 +- ui/src/pages/new-session/discovery.ts | 37 +- .../pages/new-session/draft-gateway-state.ts | 31 +- ui/src/pages/new-session/new-session-page.ts | 1 + .../new-session/place-picker-sections.ts | 25 + ui/src/pages/new-session/place-picker.test.ts | 117 +++ ui/src/pages/new-session/place-picker.ts | 70 +- .../pages/new-session/recent-places.test.ts | 9 +- ui/src/styles/chat/split-view.css | 38 +- 58 files changed, 2841 insertions(+), 310 deletions(-) create mode 100644 src/gateway/server-methods/projects-observed.test.ts create mode 100644 ui/src/e2e/new-session-page.projects-places.e2e.test.ts create mode 100644 ui/src/pages/chat/chat-pane-placement.test.ts create mode 100644 ui/src/pages/chat/chat-pane-placement.ts create mode 100644 ui/src/pages/chat/components/chat-pane-placement.ts create mode 100644 ui/src/pages/new-session/place-picker-sections.ts diff --git a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt index e7e0b5e59eb5..0e838d5cf753 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt @@ -166,6 +166,13 @@ data class WorkerDesktopLaunchResult( val status: String = "ready", ) +@Serializable +data class ProjectsListResult( + val projects: List, + val recents: List? = null, + val observedProjects: List? = null, +) + @Serializable data class GatewayEventFrameStateVersion( val presence: Long, @@ -178,6 +185,30 @@ data class GatewayNodeInvokeResultParamsError( val message: String? = null, ) +@Serializable +data class ProjectsListResultProjectsItem( + val id: String, + val displayName: String, + val repoRoot: String? = null, + val originUrl: String? = null, + val source: String, + val agentId: String? = null, +) + +@Serializable +data class ProjectsListResultObservedProjectsItem( + val name: String, + val originUrl: String? = null, + val checkouts: List, + val lastUsedAt: Double, +) + +@Serializable +data class ProjectsListResultObservedProjectsItemCheckoutsItem( + val runnerId: String, + val path: String, +) + enum class GatewayMethod( val rawValue: String, ) { diff --git a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayProtocolGeneratedTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayProtocolGeneratedTest.kt index 84ebe30e2bd4..d30f4bd80ff8 100644 --- a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayProtocolGeneratedTest.kt +++ b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayProtocolGeneratedTest.kt @@ -46,6 +46,14 @@ class GatewayProtocolGeneratedTest { assertEquals(5_000L, decoded.timeoutMs) } + @Test + fun projectsListResultDecodesALegacyProjectsOnlyPayload() { + val decoded = json.decodeFromString(ProjectsListResult.serializer(), """{"projects":[]}""") + + assertTrue(decoded.projects.isEmpty()) + assertNull(decoded.observedProjects) + } + @Test fun generatedGatewayCatalogsAreCompleteAndUnique() { val methods = GatewayMethod.entries.map { it.rawValue } diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift index a452c6140789..4054619e80ad 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift @@ -2183,6 +2183,50 @@ public struct WorkerDesktopLaunchResult: Codable, Sendable { } } +public struct ProjectCheckout: Codable, Sendable { + public let runnerid: String + public let path: String + + public init( + runnerid: String, + path: String) + { + self.runnerid = runnerid + self.path = path + } + + private enum CodingKeys: String, CodingKey { + case runnerid = "runnerId" + case path + } +} + +public struct ProjectSummary: Codable, Sendable { + public let name: String + public let originurl: String? + public let checkouts: [ProjectCheckout] + public let lastusedat: Double + + public init( + name: String, + originurl: String? = nil, + checkouts: [ProjectCheckout], + lastusedat: Double) + { + self.name = name + self.originurl = originurl + self.checkouts = checkouts + self.lastusedat = lastusedat + } + + private enum CodingKeys: String, CodingKey { + case name + case originurl = "originUrl" + case checkouts + case lastusedat = "lastUsedAt" + } +} + public struct SystemInfoParams: Codable, Sendable {} public struct SystemInfoResult: Codable, Sendable { @@ -3165,23 +3209,39 @@ public struct ProjectRecentProject: Codable, Sendable { } } -public struct ProjectsListParams: Codable, Sendable {} +public struct ProjectsListParams: Codable, Sendable { + public let includeobserved: Bool? + + public init( + includeobserved: Bool? = nil) + { + self.includeobserved = includeobserved + } + + private enum CodingKeys: String, CodingKey { + case includeobserved = "includeObserved" + } +} public struct ProjectsListResult: Codable, Sendable { public let projects: [ProjectsAddResult] public let recents: [ProjectRecent]? + public let observedprojects: [ProjectSummary]? public init( projects: [ProjectsAddResult], - recents: [ProjectRecent]? = nil) + recents: [ProjectRecent]? = nil, + observedprojects: [ProjectSummary]? = nil) { self.projects = projects self.recents = recents + self.observedprojects = observedprojects } private enum CodingKeys: String, CodingKey { case projects case recents + case observedprojects = "observedProjects" } } diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayProtocolGeneratedModelsTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayProtocolGeneratedModelsTests.swift index 0b662155e8b6..dc05ff0035ec 100644 --- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayProtocolGeneratedModelsTests.swift +++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayProtocolGeneratedModelsTests.swift @@ -68,4 +68,14 @@ struct GatewayProtocolGeneratedModelsTests { #expect(additive.scopes == ["operator.read"]) #expect(additive.locale == "en-US") } + + @Test + func `projects list result decodes a legacy projects-only payload`() throws { + let result = try JSONDecoder().decode( + ProjectsListResult.self, + from: Data(#"{"projects":[]}"#.utf8)) + + #expect(result.projects.isEmpty) + #expect(result.observedprojects == nil) + } } diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json index 706088d0dc2d..71e7a14df4c3 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json @@ -1 +1 @@ -{"contentHash":"92f86077bf8bd7e0ade16592677b6e824e8ace048e40849aa5fd5cd9fe17f280","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} +{"contentHash":"8c6ff70bbf195705355c6599c50819065f5f350f0faaddc4a868b5e86da65e28","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json index 911561a94fd2..24728a1bca39 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json @@ -1 +1 @@ -{"contentHash":"82523c6b1d5b8bc1b0933455ef0d8f798fb938e2b0e2676a434522926fd1d1ed","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} +{"contentHash":"91311c46d7fa124d5b79e0a8a6640f2ef8436c5000c1dafa3391f8c1303054b7","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-core.json b/docs/.generated/plugin-sdk-api-baseline/channel-core.json index 75b83b372c06..a546efe66f2f 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-core.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-core.json @@ -1 +1 @@ -{"contentHash":"b771ba5e57fca93e4b49512f7cde5cd1c1b0fe4cf247985aeae5bfd44cb54923","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} +{"contentHash":"c3b22d889dc4c65a0ab8c4f5743e49df7f18a399a77b271a56e2cd60a2671fea","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json index 94540322a878..4bddaffac84c 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json @@ -1 +1 @@ -{"contentHash":"8bc9cfdf0f7299079e3d39ce377b1eb8cf2b4b99ff39d3f8ceee1f7ac72d0dbd","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} +{"contentHash":"7cc678c87c2d6063305951bc9bcd75f78f4fe2a9408a263bc1cb294c66075b50","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-message.json b/docs/.generated/plugin-sdk-api-baseline/channel-message.json index 96aadff0c4d3..505d71483049 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-message.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-message.json @@ -1 +1 @@ -{"contentHash":"69ed324324c86ad863f2804fd60dfc61f6b79040ee34fa52d33d1277857db4b1","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} +{"contentHash":"f30a3ff93dab57ce1a6e73c10b027d2bb748968cd87cda27228654fc41811a03","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json index 51b4f05da2d5..251f4ea554dc 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json @@ -1 +1 @@ -{"contentHash":"a98fa525383537f792dfc06ffb40d1a89cf7c5d1d381e253178f5a2ebad79276","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} +{"contentHash":"b6ef4ba8c3840141bff65a7fee3a5ea8efbe3da79696f5d59b41f8ccf1e32914","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json index 2f5c29760554..4da75b1b6b96 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json @@ -1 +1 @@ -{"contentHash":"8fdceb1f341434d335cbbb84052651df83b29436d1016c694461b072a75121c1","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} +{"contentHash":"43afd1b1996e17f373e75c3922cbea6a0223782b0b68f6d05f7c29bbd83b8ebb","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} diff --git a/docs/.generated/plugin-sdk-api-baseline/core.json b/docs/.generated/plugin-sdk-api-baseline/core.json index ee55b7e02682..ceac45434780 100644 --- a/docs/.generated/plugin-sdk-api-baseline/core.json +++ b/docs/.generated/plugin-sdk-api-baseline/core.json @@ -1 +1 @@ -{"contentHash":"121f16d39c0b147393ca289221d4b020856a661dfc989dc978b5a499bfce5222","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} +{"contentHash":"4d6021d0ae4ad15e1ce39d8700756ec415d604606ed538240c8f8aa9bf0acc37","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/discord.json b/docs/.generated/plugin-sdk-api-baseline/discord.json index 5a43a582629b..a581faedc4ea 100644 --- a/docs/.generated/plugin-sdk-api-baseline/discord.json +++ b/docs/.generated/plugin-sdk-api-baseline/discord.json @@ -1 +1 @@ -{"contentHash":"00e179ad017e2921d85f9d2ffcf5f9e1bb415984d19e6fdc62a1832dbee659b0","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} +{"contentHash":"17eaa6392ffdf071bbe104a7c5720892042a906109be42478dec03b8bf5291a0","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} diff --git a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json index 1751f4ed359a..f232b4541473 100644 --- a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json @@ -1 +1 @@ -{"contentHash":"e31574637f3e276338e3e05e4774f7ad79981042c8021e49fb53df7ffe901917","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} +{"contentHash":"176c5db037a1e5b685c0550aeee46186b3273e8da4bbb8a720a074596598e8cc","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json index 2bdb8846687f..7c0976da00ab 100644 --- a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json +++ b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json @@ -1 +1 @@ -{"contentHash":"bfde664c63043f9719c8c12ef1e144dc387c05348b0f8b26bb2156438518dc21","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} +{"contentHash":"7bbbe7b8509abe241992eb632b1b484df2c270534f485ecf0f80e48b5671566a","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} diff --git a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json index d8be367b6c13..94e70da01e84 100644 --- a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json @@ -1 +1 @@ -{"contentHash":"2608b548ecca0c2981d80bff3596982d74572558c0fe7eb846a971880b1563af","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} +{"contentHash":"00ae2e13016a7ba0ebd4baef8b34a2b3811e0221799f6351d2189f6e0ea694ba","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json index f655ce4ffdbd..474c9c965de1 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json @@ -1 +1 @@ -{"contentHash":"8220986c0c848a5fe05c909f5c0626a6ebe0800fe5517a196718d4f21d30ebb6","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} +{"contentHash":"e20acaab6a8d3d56b57a487168439da89adfe250f0474a4c53350424415ac498","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json index 4d3025465523..0dd7bab53d6f 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json @@ -1 +1 @@ -{"contentHash":"8350a80731ab2e020c859ea1994acd004fbaa9ca9c0d92fb09acd8703bc79ed3","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} +{"contentHash":"31e0fb8e73f98c8f69f8808aec8d8dc18fc2a074a21b9fc82414729fa1acceee","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json index f7fcdd9e6351..1661414f0136 100644 --- a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json @@ -1 +1 @@ -{"contentHash":"f61cc543e5d007e5da4951ccc61e12fc107fed478dfc8285b37389a77d2a6224","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} +{"contentHash":"4918ded36f8fc0701bd94e4be965577c1c035977e6c5d32db1c17862775d6318","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json index ffa394876c59..bc034e25fcc5 100644 --- a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json +++ b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json @@ -1 +1 @@ -{"contentHash":"f27ec37aa7c772f12aeda7b8aa969b34a7a7bb7877e6d95b26a8b3e9174f4899","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} +{"contentHash":"cd199186dee1148dc53d05710cb9785fdcff475bedbc92f5c18b5ddca675dbe7","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} diff --git a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json index 7b8b290d000f..92ab4d7a41d3 100644 --- a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json +++ b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json @@ -1 +1 @@ -{"contentHash":"6579285290ce10e5bf4ae930bbb2d28de52672fc4c7dd0f55f0dcdc1d711d3c1","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} +{"contentHash":"265be26af18bed1c86ddc4636df78ac2f064848dcfc9e9da8e05842c69750ba4","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} diff --git a/docs/plan/runners.md b/docs/plan/runners.md index 4d3765f0ed74..88fab30f0dfc 100644 --- a/docs/plan/runners.md +++ b/docs/plan/runners.md @@ -21,7 +21,7 @@ advances a milestone. | 1c | Cleanup: node-pairing → device-pairing merge | not started | — | | 2 | `openclaw resume` + web Continue in terminal | in progress | #120664 | | 3 | `openclaw connect` one-paste onboarding + `/j/` join route | not started | — | -| 4 | Picker: liveness, enrichment, Connect-a-machine | not started | — | +| 4 | Picker: grouping, placement, liveness, enrichment | in progress | #120804 | | 5 | Public worker ingress path | not started | — | | 6 | Node worker provider (device runners) | not started | — | | 7 | Bundle push consent + runner updates | not started | — | @@ -272,24 +272,46 @@ it cannot rot into approval fatigue or silent surprise: dispatch to stale nodes with a doctor-style hint instead of failing silently. +### Projects read model (milestone 4 foundation) + +OpenClaw already computes project identity twice without naming it: the +worktree service derives `originUrl` + a 16-char repo fingerprint +(`src/agents/worktrees/service.ts:199-205`), and the sessions catalog groups +Codex/Claude rows by project folder, folding `.claude/worktrees/` into +its origin repo. This component promotes that to a first-class observed read +model alongside the registered projects already returned by `projects.list`, +following the same computed pattern as `environments.list`: + +- **`projects.list.observedProjects` read model** (computed for + write-capable callers, no new store): group known checkouts by repo fingerprint → `{ name, originUrl, checkouts: +[{runnerId, path}], lastUsedAt }`. Sources: session rows + (`execCwd`/`execNode`) and the managed-worktree registry. The observed + paths and sanitized origins are returned only to `operator.write` callers; + read-only callers keep the registered project catalog and project-only + recents. Device-advertised checkouts remain milestone 6 work. + ### UI (milestone 4) Revision 1's design rule stands: normal state is silent; only exceptions speak. Additions: -- The Where picker subscribes to `presence` and pairing events (the devices - page already does), so a freshly connected machine appears live while the - popover is open — the visible payoff of the one-paste flow. -- Sections "This gateway / Your devices / Cloud"; session-capable connected - devices only (capability-gated); busy state from slot occupancy; presence - vocabulary distinguishes _never connected_ from _was connected, lost_ - (the first-connect failure is the top onboarding support case). -- `EnvironmentSummary` enriched additively: platform, session-host - capability, trust class, runner version. -- Placement chip on the session header: current placement + state; reclaim - ("Bring home") for remote placements; stop-and-continue moves once - milestone 8 ships. `runner-offline` shows as a banner with the recorded - reason and the two recovery verbs. +- **Use the existing environment type discriminant** for picker grouping: + local gateway, connected execution-capable nodes, worker environments, and + the separate cloud profiles list. `sessionHost` is deferred to milestone 6, + where device runners introduce the capability fact that needs it. +- **Where picker regrouped** (`ui/src/pages/new-session/place-picker.ts`): + sections "This gateway" / "Devices" / "Cloud". Device rows intersect the + environment catalog with connected, execution-capable nodes; cloud + profiles remain their separate list. Folder and destination stay + orthogonal. +- **Placement chip** on the session header: shows quiet current placement; + active cloud placements reclaim through `sessions.reclaim` with "Bring + home". Stop-and-continue moves arrive with milestone 8. +- **Remaining milestone work**: live presence and pairing subscriptions, the + admin-gated "Connect a machine…" foot, busy and never-connected states, + and additive `EnvironmentSummary` platform, session-host, trust, and runner + version facts. `runner-offline` then shows a banner with the recorded reason + and its recovery verbs. ### Cloud convergence (milestone 10) @@ -370,9 +392,10 @@ Independently mergeable PR series; 3–5 can interleave after 1c. shortcode mint + curl wrapper on the public site. Exit: a fresh machine pairs against a remote gateway with one pasted command and one admin click, no manual approval steps. -4. **Picker**: live presence subscription; "Connect a machine…" foot - (admin-gated) showing the copyable one-liner; regrouped sections; additive - `EnvironmentSummary` enrichment; never-connected vs lost states. +4. **Picker** (in progress): regrouped sections, quiet placement + reclaim, + and the observed projects read model land first; live presence subscription, + the admin-gated "Connect a machine…" foot, additive `EnvironmentSummary` + enrichment, and never-connected vs lost states complete the milestone. 5. **Public worker ingress**: path-tagged worker upgrade on the main TLS endpoint; opaque admission failure; shared preauth budgets. Exit: a worker process on any internet host with a valid dispatch credential completes diff --git a/packages/gateway-protocol/src/index.ts b/packages/gateway-protocol/src/index.ts index a89b94a37e7e..a4ffa3eeba41 100644 --- a/packages/gateway-protocol/src/index.ts +++ b/packages/gateway-protocol/src/index.ts @@ -37,6 +37,7 @@ export { } from "./schema/sessions-row.js"; export * from "./schema/session-classification.js"; export * from "./schema/sessions-suggestions.js"; +export * from "./schema/projects.js"; export * from "./migration-api.js"; export type * from "./public-session-catalog.js"; export * from "./validator-registry.js"; diff --git a/packages/gateway-protocol/src/schema/projects.test.ts b/packages/gateway-protocol/src/schema/projects.test.ts index a67ffe651df9..26024f679724 100644 --- a/packages/gateway-protocol/src/schema/projects.test.ts +++ b/packages/gateway-protocol/src/schema/projects.test.ts @@ -1,8 +1,11 @@ import { Value } from "typebox/value"; import { describe, expect, it } from "vitest"; import { + PROJECTS_LIST_DEFAULT_LIMIT, + PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT, ProjectRecordSchema, ProjectsAddResultSchema, + ProjectSummarySchema, ProjectsListResultSchema, ProjectsSearchRemoteResultSchema, validateProjectsAddParams, @@ -16,6 +19,9 @@ import { describe("project protocol schemas", () => { it("validates project method inputs as closed objects", () => { expect(validateProjectsListParams({})).toBe(true); + expect(validateProjectsListParams({ includeObserved: true })).toBe(true); + expect(validateProjectsListParams({ includeObserved: false })).toBe(true); + expect(validateProjectsListParams({ includeObserved: "yes" })).toBe(false); expect(validateProjectsListParams({ extra: true })).toBe(false); expect(validateProjectsRegisterParams({ path: "/repo", name: "OpenClaw" })).toBe(true); expect(validateProjectsRegisterParams({ path: "" })).toBe(false); @@ -79,9 +85,36 @@ describe("project protocol schemas", () => { { kind: "project", projectId: "openclaw", displayName: "OpenClaw" }, { kind: "folder", folder: "/repo/scratch", displayName: "scratch" }, ], + observedProjects: [], }), ).toBe(true); expect(Value.Check(ProjectsListResultSchema, { projects: [] })).toBe(true); + expect(Value.Check(ProjectsListResultSchema, { observedProjects: [] })).toBe(false); + }); + + it("bounds observed projects and their checkout lists", () => { + const project = { + name: "openclaw", + originUrl: "https://github.com/openclaw/openclaw.git", + checkouts: [{ runnerId: "gateway", path: "/repo/openclaw" }], + lastUsedAt: 1, + }; + expect(Value.Check(ProjectSummarySchema, project)).toBe(true); + expect( + Value.Check(ProjectSummarySchema, { + ...project, + checkouts: Array.from( + { length: PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT + 1 }, + (_, index) => ({ runnerId: "gateway", path: `/repo/openclaw-${index}` }), + ), + }), + ).toBe(false); + expect( + Value.Check(ProjectsListResultSchema, { + projects: [], + observedProjects: Array.from({ length: PROJECTS_LIST_DEFAULT_LIMIT + 1 }, () => project), + }), + ).toBe(false); }); it("accepts projectId as an additive sessions.create parameter", () => { diff --git a/packages/gateway-protocol/src/schema/projects.ts b/packages/gateway-protocol/src/schema/projects.ts index b9052ad35add..30ab05ee141a 100644 --- a/packages/gateway-protocol/src/schema/projects.ts +++ b/packages/gateway-protocol/src/schema/projects.ts @@ -7,6 +7,10 @@ const StoredProjectIdSchema = Type.String({ pattern: "^[a-z0-9][a-z0-9-]{0,63}$", }); +export const PROJECTS_LIST_DEFAULT_LIMIT = 50; +export const PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT = 50; +export const PROJECTS_LIST_MAX_IDENTITY_PROBES = 32; + export const ProjectRecordSchema = closedObject({ id: NonEmptyString, displayName: NonEmptyString, @@ -44,10 +48,50 @@ export const ProjectRecentSchema = Type.Union([ ProjectRecentFolderSchema, ]); -export const ProjectsListParamsSchema = closedObject({}); +/** One gateway-visible checkout for an observed repository project. */ +export const ProjectCheckoutSchema = closedObject({ + runnerId: Type.String({ + minLength: 1, + description: "Runner hosting this operator.write-scoped checkout.", + }), + path: Type.String({ + minLength: 1, + description: "Physical checkout path returned only to operator.write-capable callers.", + }), +}); + +/** Repository identity derived from visible checkout and session state. */ +export const ProjectSummarySchema = closedObject({ + name: NonEmptyString, + originUrl: Type.Optional( + Type.String({ + minLength: 1, + description: "Sanitized repository origin returned to operator.write-capable callers.", + }), + ), + checkouts: Type.Array(ProjectCheckoutSchema, { + minItems: 1, + maxItems: PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT, + }), + lastUsedAt: Type.Number({ minimum: 0 }), +}); + +export const ProjectsListParamsSchema = closedObject({ + includeObserved: Type.Optional( + Type.Boolean({ + description: "Compute write-scoped observed checkout groups in addition to projects.", + }), + ), +}); export const ProjectsListResultSchema = closedObject({ projects: Type.Array(ProjectRecordSchema), recents: Type.Optional(Type.Array(ProjectRecentSchema, { maxItems: 8 })), + observedProjects: Type.Optional( + Type.Array(ProjectSummarySchema, { + maxItems: PROJECTS_LIST_DEFAULT_LIMIT, + description: "Observed checkout details returned only to operator.write-capable callers.", + }), + ), }); export const ProjectsRegisterParamsSchema = closedObject({ @@ -86,6 +130,8 @@ export const ProjectsRemoveResultSchema = closedObject({ removed: Type.Boolean() export type ProjectRecord = Static; export type ProjectRecent = Static; +export type ProjectCheckout = Static; +export type ProjectSummary = Static; export type ProjectsListParams = Static; export type ProjectsListResult = Static; export type ProjectsRegisterParams = Static; diff --git a/packages/gateway-protocol/src/schema/protocol-schema-fragment-agent-control.ts b/packages/gateway-protocol/src/schema/protocol-schema-fragment-agent-control.ts index 29e4fe56a3b9..2e61aac04f96 100644 --- a/packages/gateway-protocol/src/schema/protocol-schema-fragment-agent-control.ts +++ b/packages/gateway-protocol/src/schema/protocol-schema-fragment-agent-control.ts @@ -24,6 +24,8 @@ export const AgentControlProtocolSchemas = { WorkerDesktopObserveResult: environments.WorkerDesktopObserveResultSchema, WorkerDesktopLaunchParams: environments.WorkerDesktopLaunchParamsSchema, WorkerDesktopLaunchResult: environments.WorkerDesktopLaunchResultSchema, + ProjectCheckout: projects.ProjectCheckoutSchema, + ProjectSummary: projects.ProjectSummarySchema, SystemInfoParams: systemInfo.SystemInfoParamsSchema, SystemInfoResult: systemInfo.SystemInfoResultSchema, AgentEvent: agent.AgentEventSchema, diff --git a/scripts/protocol-gen-kotlin.ts b/scripts/protocol-gen-kotlin.ts index 31731a81d7a6..4291d46d3439 100644 --- a/scripts/protocol-gen-kotlin.ts +++ b/scripts/protocol-gen-kotlin.ts @@ -60,6 +60,7 @@ const schemaNames = new Map([ ["WorkerDesktopObserveResult", "WorkerDesktopObserveResult"], ["WorkerDesktopLaunchParams", "WorkerDesktopLaunchParams"], ["WorkerDesktopLaunchResult", "WorkerDesktopLaunchResult"], + ["ProjectsListResult", "ProjectsListResult"], ]); const androidEnums: EnumSpec[] = [ diff --git a/src/agents/worktrees/service.test.ts b/src/agents/worktrees/service.test.ts index 0c5dc96515f0..f8d88e252a26 100644 --- a/src/agents/worktrees/service.test.ts +++ b/src/agents/worktrees/service.test.ts @@ -159,6 +159,21 @@ describe("ManagedWorktreeService", () => { expect(repeated).toEqual(created); }); + it("reads registry records without retiring a temporarily unavailable worktree", async () => { + const created = await service.create({ + repoRoot: repo, + name: "read-only-list", + baseRef: "HEAD", + }); + await fs.rm(created.path, { recursive: true, force: true }); + + expect(service.listRegistryRecords()).toEqual([expect.objectContaining({ id: created.id })]); + expect(getRegistryWorktree(env, created.id)?.removedAt).toBeUndefined(); + + expect(await service.list()).toEqual([]); + expect(getRegistryWorktree(env, created.id)?.removedAt).toBe(now); + }); + it("does not remove a worktree owned by another caller", async () => { const created = await service.create({ repoRoot: repo, diff --git a/src/agents/worktrees/service.ts b/src/agents/worktrees/service.ts index c932a4b1cc5f..b7e87068c50c 100644 --- a/src/agents/worktrees/service.ts +++ b/src/agents/worktrees/service.ts @@ -772,6 +772,11 @@ export class ManagedWorktreeService { return records.filter((record) => record.removedAt === undefined || record.snapshotRef); } + /** Returns persisted worktree facts without probing paths or mutating lifecycle state. */ + listRegistryRecords(): ManagedWorktreeRecord[] { + return listRegistryWorktrees(this.env); + } + findLiveByOwner( ownerKind: ManagedWorktreeOwnerKind, ownerId: string, @@ -796,6 +801,22 @@ export class ManagedWorktreeService { }; } + /** Resolves the repository facts shared by managed worktrees and project discovery. */ + async resolveRepositoryIdentity(repoRoot: string): Promise<{ + checkoutRoot: string; + repoRoot: string; + originUrl: string; + fingerprint: string; + }> { + const resolved = await resolveRepository(repoRoot); + return { + checkoutRoot: resolved.sourceRoot, + repoRoot: resolved.repoRoot, + originUrl: resolved.originUrl, + fingerprint: resolved.fingerprint, + }; + } + /** * Lists selectable base refs for a repository without touching the network. * Base-ref pickers must stay snappy; resolveWorktreeBase() still fetches on create diff --git a/src/gateway/server-methods.authorization.test.ts b/src/gateway/server-methods.authorization.test.ts index 4e8efb6f32be..eb20f7c0fa3f 100644 --- a/src/gateway/server-methods.authorization.test.ts +++ b/src/gateway/server-methods.authorization.test.ts @@ -106,6 +106,34 @@ describe("gateway method authorization", () => { }); }); + it("allows read-only projects.list to reach its redacting handler", async () => { + const handler = vi.fn(({ respond }) => respond(true, { projects: [] })); + const respond = vi.fn(); + + await handleGatewayRequest({ + req: { type: "req", id: "req-projects-read", method: "projects.list", params: {} }, + respond, + client: { + connId: "conn-projects-read", + connect: { + role: "operator", + scopes: ["operator.read"], + client: { id: "test", version: "1", platform: "test", mode: "test" }, + minProtocol: 1, + maxProtocol: 1, + }, + } as Parameters[0]["client"], + isWebchatConnect: () => false, + context: { logGateway: { warn: vi.fn() } } as unknown as Parameters< + typeof handleGatewayRequest + >[0]["context"], + extraHandlers: { "projects.list": handler }, + }); + + expect(handler).toHaveBeenCalledOnce(); + expect(respond).toHaveBeenCalledWith(true, { projects: [] }); + }); + it("rejects every node RPC when its connection no longer owns the pairing generation", async () => { const handler = vi.fn(({ respond }) => respond(true, { ok: true })); const respond = vi.fn(); diff --git a/src/gateway/server-methods/projects-observed.test.ts b/src/gateway/server-methods/projects-observed.test.ts new file mode 100644 index 000000000000..06010a342921 --- /dev/null +++ b/src/gateway/server-methods/projects-observed.test.ts @@ -0,0 +1,308 @@ +import { isRecord } from "@openclaw/normalization-core/record-coerce"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { + PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT, + PROJECTS_LIST_MAX_IDENTITY_PROBES, +} from "../../../packages/gateway-protocol/src/index.js"; +import type { SessionEntry } from "../../config/sessions.js"; +import { createProjectsHandlers } from "./projects.js"; +import type { GatewayClient, GatewayRequestContext, RespondFn } from "./types.js"; + +type ProjectWorktreeService = Parameters[0]; + +const seededSessions = vi.hoisted(() => ({ + store: {} as Record, +})); + +vi.mock("../session-utils.js", () => ({ + loadCombinedSessionStoreForGatewayCore: () => ({ store: seededSessions.store }), +})); + +vi.mock("../../projects/project-registry.js", () => ({ + listProjectRegistry: () => [], + ProjectCheckoutError: class ProjectCheckoutError extends Error {}, + registerProjectRegistry: vi.fn(), + removeProjectRegistry: vi.fn(), +})); + +function authenticatedClient(user: string, scopes = ["operator.write"]): GatewayClient { + return { + connect: { + minProtocol: 1, + maxProtocol: 1, + client: { + id: "openclaw-control-ui", + version: "test", + platform: "test", + mode: "webchat", + }, + role: "operator", + scopes, + }, + authenticatedUserId: user, + authenticatedUserProfile: { + profileId: user, + displayName: user, + hasAvatar: false, + updatedAt: 1, + }, + }; +} + +function assertObservedProjectsPayload( + payload: unknown, +): asserts payload is { observedProjects: unknown[] } { + if (!isRecord(payload) || !Array.isArray(payload.observedProjects)) { + throw new TypeError("projects.list response is missing observedProjects"); + } +} + +async function listObservedProjects(params: { + service: { + listRegistryRecords: () => unknown[]; + resolveRepositoryIdentity: (checkoutPath: string) => Promise<{ + checkoutRoot: string; + repoRoot: string; + originUrl: string; + fingerprint: string; + }>; + }; + client?: GatewayClient; +}) { + const handlers = createProjectsHandlers(params.service as never); + const responses: Parameters[] = []; + await handlers["projects.list"]?.({ + params: { includeObserved: true }, + respond: (...response: Parameters) => responses.push(response), + context: { + getRuntimeConfig: () => ({ agents: { list: [{ id: "main", default: true }] } }), + } as GatewayRequestContext, + client: params.client ?? authenticatedClient("operator@example.com"), + } as never); + expect(responses).toHaveLength(1); + const response = responses[0]; + if (!response) { + throw new Error("projects.list did not respond"); + } + expect(response[0]).toBe(true); + assertObservedProjectsPayload(response[1]); + return response[1].observedProjects; +} + +beforeEach(() => { + seededSessions.store = {}; +}); + +describe("projects.list observed projects", () => { + it.each([["operator.write"], ["operator.admin"]])( + "returns detailed observed projects to %s callers", + async (scope) => { + seededSessions.store = { + "agent:main:old": { + sessionId: "old", + updatedAt: 100, + execCwd: "/links/alpha-old", + }, + "agent:main:new": { + sessionId: "new", + updatedAt: 300, + execCwd: "/links/alpha-new", + }, + "agent:main:device": { + sessionId: "device", + updatedAt: 400, + execCwd: "/device/alpha", + execNode: "paired-mac", + }, + }; + const resolveRepositoryIdentity = vi.fn(async (checkoutPath: string) => ({ + checkoutRoot: checkoutPath.replace("/links/", "/physical/"), + repoRoot: "/physical/alpha", + originUrl: "https://github.com/openclaw/alpha.git", + fingerprint: "alpha-fingerprint", + })); + + await expect( + listObservedProjects({ + service: { listRegistryRecords: () => [], resolveRepositoryIdentity }, + client: authenticatedClient(`${scope}@example.com`, [scope]), + }), + ).resolves.toEqual([ + { + name: "alpha-new", + originUrl: "https://github.com/openclaw/alpha.git", + checkouts: [ + { runnerId: "gateway", path: "/physical/alpha-new" }, + { runnerId: "gateway", path: "/physical/alpha-old" }, + ], + lastUsedAt: 300, + }, + ]); + expect(resolveRepositoryIdentity).not.toHaveBeenCalledWith("/device/alpha"); + }, + ); + + it("admits managed worktrees only when their owning session is visible", async () => { + seededSessions.store = { + "agent:main:visible": { + sessionId: "visible", + updatedAt: 200, + visibility: "shared", + createdActor: { type: "human", id: "owner@example.com" }, + }, + "agent:main:private": { + sessionId: "private", + updatedAt: 300, + visibility: "draft", + createdActor: { type: "human", id: "owner@example.com" }, + }, + }; + const worktree = (name: string, ownerId: string, lastActiveAt: number) => ({ + id: name, + name, + repoFingerprint: name, + repoRoot: `/repos/${name}`, + path: `/worktrees/${name}`, + branch: `openclaw/${name}`, + baseRef: "main", + ownerKind: "session", + ownerId, + createdAt: 100, + lastActiveAt, + }); + const worktrees = [ + worktree("visible", "agent:main:visible", 500), + worktree("private", "agent:main:private", 490), + worktree("orphan", "agent:main:missing", 480), + { + ...worktree("manual", "ignored", 470), + ownerKind: "manual", + ownerId: undefined, + }, + ]; + const resolveRepositoryIdentity = vi.fn(async (checkoutPath: string) => ({ + checkoutRoot: checkoutPath, + repoRoot: checkoutPath, + originUrl: `https://example.test${checkoutPath}.git`, + fingerprint: checkoutPath, + })); + const service = { listRegistryRecords: () => worktrees, resolveRepositoryIdentity }; + + const viewer = (await listObservedProjects({ + service, + client: authenticatedClient("viewer@example.com"), + })) as Array<{ name: string }>; + expect(viewer.map((project) => project.name)).toEqual(["visible"]); + + const admin = (await listObservedProjects({ + service, + client: authenticatedClient("admin@example.com", ["operator.admin"]), + })) as Array<{ name: string }>; + expect(admin.map((project) => project.name)).toEqual([ + "visible", + "private", + "orphan", + "manual", + ]); + }); + + it("redacts URL and SCP-style userinfo and omits unknown remote forms", async () => { + seededSessions.store = Object.fromEntries( + ["url", "token-scp", "git-scp", "unknown"].map((name, index) => [ + `agent:main:${name}`, + { sessionId: name, updatedAt: 400 - index, execCwd: `/repos/${name}` }, + ]), + ); + const origins: Record = { + "/repos/url": ["https://user", ":placeholder", "@host/repo.git?visible=value#branch"].join( + "", + ), + "/repos/token-scp": ["placeholder", "@host:org/private.git"].join(""), + "/repos/git-scp": "git@host:org/public.git", + "/repos/unknown": "opaque credential-shaped remote", + }; + + const projects = (await listObservedProjects({ + service: { + listRegistryRecords: () => [], + resolveRepositoryIdentity: async (checkoutPath: string) => ({ + checkoutRoot: checkoutPath, + repoRoot: checkoutPath, + originUrl: origins[checkoutPath] ?? "", + fingerprint: checkoutPath, + }), + }, + })) as Array<{ name: string; originUrl?: string }>; + + expect(projects.map(({ name, originUrl }) => ({ name, originUrl }))).toEqual([ + { name: "url", originUrl: "https://host/repo.git" }, + { name: "token-scp", originUrl: "host:org/private.git" }, + { name: "git-scp", originUrl: "host:org/public.git" }, + { name: "unknown", originUrl: undefined }, + ]); + }); + + it("caps checkout arrays in deterministic newest-first order", async () => { + const worktrees = Array.from( + { length: PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT + 3 }, + (_, index) => ({ + id: `worktree-${index}`, + name: `worktree-${index}`, + repoFingerprint: "alpha-fingerprint", + repoRoot: "/repos/alpha", + path: `/worktrees/${String(index).padStart(2, "0")}`, + branch: `openclaw/worktree-${index}`, + baseRef: "main", + ownerKind: "manual", + createdAt: 1, + lastActiveAt: index, + }), + ); + + const projects = (await listObservedProjects({ + service: { + listRegistryRecords: () => worktrees, + resolveRepositoryIdentity: async (checkoutPath: string) => ({ + checkoutRoot: checkoutPath, + repoRoot: checkoutPath, + originUrl: "https://github.com/openclaw/alpha.git", + fingerprint: "alpha-fingerprint", + }), + }, + client: authenticatedClient("admin@example.com", ["operator.admin"]), + })) as Array<{ checkouts: Array<{ path: string }> }>; + + expect(projects[0]?.checkouts).toHaveLength(PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT); + expect(projects[0]?.checkouts[0]?.path).toBe("/worktrees/52"); + expect(projects[0]?.checkouts.at(-1)?.path).toBe("/worktrees/03"); + }); + + it("retains only the newest bounded candidates before identity resolution", async () => { + const rawCandidateLimit = Math.max( + PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT, + PROJECTS_LIST_MAX_IDENTITY_PROBES, + 50, + ); + seededSessions.store = Object.fromEntries( + Array.from({ length: rawCandidateLimit + 5 }, (_, index) => [ + `agent:main:session-${index}`, + { sessionId: `session-${index}`, updatedAt: index, execCwd: `/repos/${index}` }, + ]), + ); + const resolveRepositoryIdentity = vi.fn( + async (_checkoutPath) => { + throw new Error("checkout unavailable"); + }, + ); + + await expect( + listObservedProjects({ + service: { listRegistryRecords: () => [], resolveRepositoryIdentity }, + }), + ).resolves.toEqual([]); + expect(resolveRepositoryIdentity).toHaveBeenCalledTimes(PROJECTS_LIST_MAX_IDENTITY_PROBES); + expect(resolveRepositoryIdentity.mock.calls.length).toBeLessThanOrEqual(rawCandidateLimit); + expect(resolveRepositoryIdentity.mock.calls[0]?.[0]).toBe(`/repos/${rawCandidateLimit + 4}`); + expect(resolveRepositoryIdentity).not.toHaveBeenCalledWith("/repos/0"); + }); +}); diff --git a/src/gateway/server-methods/projects.test.ts b/src/gateway/server-methods/projects.test.ts index acf394265d94..36106274b445 100644 --- a/src/gateway/server-methods/projects.test.ts +++ b/src/gateway/server-methods/projects.test.ts @@ -2,7 +2,7 @@ import { execFile } from "node:child_process"; import fs from "node:fs/promises"; import path from "node:path"; import { promisify } from "node:util"; -import { expect, test } from "vitest"; +import { beforeEach, expect, test, vi } from "vitest"; import { insertRegistryWorktree } from "../../agents/worktrees/registry.js"; import { replaceSessionEntrySync } from "../../config/sessions/session-accessor.js"; import { upsertSessionEntryCore } from "../../config/sessions/session-accessor.js"; @@ -14,9 +14,25 @@ import { } from "../../projects/project-registry.js"; import { ensureProfileForEmail, linkEmail } from "../../state/user-profiles.js"; import { createOpenClawTestState } from "../../test-utils/openclaw-test-state.js"; -import { projectsHandlers } from "./projects.js"; +import { createProjectsHandlers } from "./projects.js"; const execFileAsync = promisify(execFile); +const listRegistryRecords = vi.fn(() => []); +const resolveRepositoryIdentity = vi.fn(async (checkoutPath: string) => ({ + checkoutRoot: checkoutPath, + repoRoot: checkoutPath, + originUrl: "", + fingerprint: checkoutPath, +})); +const projectsHandlers = createProjectsHandlers({ + listRegistryRecords, + resolveRepositoryIdentity, +} as never); + +beforeEach(() => { + listRegistryRecords.mockClear(); + resolveRepositoryIdentity.mockClear(); +}); async function initializeRepository( root: string, @@ -117,8 +133,18 @@ test("projects.list exposes checkout details only at write scope", async () => { expect(project).not.toHaveProperty("repoRoot"); expect(project).not.toHaveProperty("originUrl"); } + expect(readResult.payload).not.toHaveProperty("observedProjects"); + expect(listRegistryRecords).not.toHaveBeenCalled(); + expect(resolveRepositoryIdentity).not.toHaveBeenCalled(); + + const readOptIn = await invokeProjectMethod("projects.list", { includeObserved: true }, cfg, [ + "operator.read", + ]); + expect(readOptIn?.payload).not.toHaveProperty("observedProjects"); + expect(listRegistryRecords).not.toHaveBeenCalled(); for (const scope of ["operator.write", "operator.admin"]) { + const callsBeforeDefaultList = listRegistryRecords.mock.calls.length; const writeResult = await invokeProjectMethod("projects.list", {}, cfg, [scope]); expect(writeResult).toMatchObject({ ok: true, @@ -133,7 +159,60 @@ test("projects.list exposes checkout details only at write scope", async () => { ], }, }); + expect(writeResult?.payload).not.toHaveProperty("observedProjects"); + expect(listRegistryRecords).toHaveBeenCalledTimes(callsBeforeDefaultList); + + const observedResult = await invokeProjectMethod( + "projects.list", + { includeObserved: true }, + cfg, + [scope], + ); + expect(observedResult).toMatchObject({ + ok: true, + payload: { observedProjects: [] }, + }); } + expect(listRegistryRecords).toHaveBeenCalledTimes(2); + } finally { + await state.cleanup(); + } +}); + +test("project responses redact credentials and URL suffixes from registered origins", async () => { + const state = await createOpenClawTestState({ layout: "state-only", prefix: "projects-rpc-" }); + try { + const repo = await initializeRepository(state.root); + await execFileAsync("git", [ + "-C", + repo, + "remote", + "set-url", + "origin", + ["https://user", ":placeholder", "@host/private.git?visible=value#branch"].join(""), + ]); + + const registered = await invokeProjectMethod( + "projects.register", + { path: repo, name: "Private" }, + {}, + ["operator.admin"], + ); + expect(registered).toMatchObject({ + ok: true, + payload: { originUrl: "https://host/private.git" }, + }); + + const listed = await invokeProjectMethod("projects.list", {}, {}, ["operator.write"]); + expect(listed).toMatchObject({ + ok: true, + payload: { + projects: expect.arrayContaining([ + expect.objectContaining({ id: "workspace:main" }), + expect.objectContaining({ id: "private", originUrl: "https://host/private.git" }), + ]), + }, + }); } finally { await state.cleanup(); } diff --git a/src/gateway/server-methods/projects.ts b/src/gateway/server-methods/projects.ts index 7e3b51961143..a4a1c4027c9d 100644 --- a/src/gateway/server-methods/projects.ts +++ b/src/gateway/server-methods/projects.ts @@ -4,14 +4,20 @@ import { ErrorCodes, GatewayErrorDetailCodes, errorShape, + PROJECTS_LIST_DEFAULT_LIMIT, + PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT, + PROJECTS_LIST_MAX_IDENTITY_PROBES, + type ProjectRecord, type ProjectRecent, validateProjectsAddParams, + type ProjectSummary, validateProjectsListParams, validateProjectsRegisterParams, validateProjectsRemoveParams, validateProjectsSearchRemoteParams, } from "../../../packages/gateway-protocol/src/index.js"; import { listRegistryWorktrees } from "../../agents/worktrees/registry.js"; +import { managedWorktrees, type ManagedWorktreeService } from "../../agents/worktrees/service.js"; import { formatErrorMessage } from "../../infra/errors.js"; import { isPathInside } from "../../infra/path-guards.js"; import { ProjectCloneError } from "../../projects/project-clone-runtime.js"; @@ -31,17 +37,118 @@ import { listProfiles, resolveUserProfileId } from "../../state/user-profiles.js import { githubApiToken } from "../control-ui-github-api.js"; import { WRITE_SCOPE, authorizeOperatorScopesForRequiredScope } from "../method-scopes.js"; import { searchRemoteProjects } from "../project-github-search.js"; +import { createSessionListEntryFilter } from "../session-sharing.js"; import { loadCombinedSessionStoreForGatewayCore } from "../session-utils.js"; import type { GatewayRequestHandlers } from "./types.js"; import { assertValidParams } from "./validation.js"; type ProjectRegistryEntry = ReturnType[number]; +type ProjectWorktreeService = Pick< + ManagedWorktreeService, + "listRegistryRecords" | "resolveRepositoryIdentity" +>; + +type ProjectCandidate = { + checkoutPath: string; + fingerprint: string; + lastUsedAt: number; + originUrl?: string; +}; + +type RawProjectCandidate = + | { kind: "session"; checkoutPath: string; lastUsedAt: number } + | { + kind: "worktree"; + checkoutPath: string; + fingerprint: string; + lastUsedAt: number; + repoRoot: string; + }; + +type ProjectGroup = { + checkouts: Map; + lastUsedAt: number; + name: string; + nameUsedAt: number; + originUrl?: string; +}; + +// This buffer must cover the largest possible response/checkouts while remaining independent of +// session history. Identity resolution has its own lower subprocess ceiling within this bound. +const PROJECTS_LIST_MAX_RAW_CANDIDATES = Math.max( + PROJECTS_LIST_DEFAULT_LIMIT, + PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT, + PROJECTS_LIST_MAX_IDENTITY_PROBES, +); function folderDisplayName(folder: string): string { const trimmed = folder.replace(/[\\/]+$/u, ""); return path.posix.basename(trimmed) || path.win32.basename(trimmed) || folder; } +function checkoutName(checkoutPath: string): string { + const trimmed = checkoutPath.replace(/[\\/]+$/u, ""); + return trimmed.split(/[\\/]/u).at(-1) || trimmed; +} + +function compareRawProjectCandidates(left: RawProjectCandidate, right: RawProjectCandidate) { + return ( + right.lastUsedAt - left.lastUsedAt || + left.checkoutPath.localeCompare(right.checkoutPath) || + left.kind.localeCompare(right.kind) + ); +} + +function retainNewestRawProjectCandidate( + candidates: RawProjectCandidate[], + candidate: RawProjectCandidate, +) { + const insertionIndex = candidates.findIndex( + (existing) => compareRawProjectCandidates(candidate, existing) < 0, + ); + if (insertionIndex < 0) { + if (candidates.length < PROJECTS_LIST_MAX_RAW_CANDIDATES) { + candidates.push(candidate); + } + return; + } + candidates.splice(insertionIndex, 0, candidate); + if (candidates.length > PROJECTS_LIST_MAX_RAW_CANDIDATES) { + candidates.pop(); + } +} + +function sanitizePublicOriginUrl(originUrl: string): string | undefined { + const trimmed = originUrl.trim(); + const suffixIndex = trimmed.search(/[?#]/u); + const withoutSuffix = suffixIndex < 0 ? trimmed : trimmed.slice(0, suffixIndex); + const scp = /^[^@\s/:]+@(\[[^\]]+\]|[^:\s]+):(.+)$/u.exec(withoutSuffix); + if (scp) { + return `${scp[1]}:${scp[2]}`; + } + let parsed: URL; + try { + parsed = new URL(withoutSuffix); + } catch { + return undefined; + } + if (!parsed.username && !parsed.password) { + return withoutSuffix; + } + parsed.username = ""; + parsed.password = ""; + return parsed.toString(); +} + +function sanitizeProjectRecord(project: ProjectRecord): ProjectRecord { + const { originUrl, ...record } = project; + const sanitizedOriginUrl = originUrl ? sanitizePublicOriginUrl(originUrl) : undefined; + return { + ...record, + ...(sanitizedOriginUrl ? { originUrl: sanitizedOriginUrl } : {}), + }; +} + function resolvePathProject( projects: readonly ProjectRegistryEntry[], folder: string, @@ -117,212 +224,395 @@ function listProjectRecents( return recents; } -export const projectsHandlers: GatewayRequestHandlers = { - "projects.list": ({ params, respond, context, client }) => { - if (!assertValidParams(params, validateProjectsListParams, "projects.list", respond)) { - return; - } - const projects = listProjectRegistry(context.getRuntimeConfig()); - const profileId = client?.authenticatedUserProfile?.profileId; - const canonicalProfileId = profileId - ? (resolveUserProfileId(profileId) ?? profileId) - : undefined; - const recentProfileIds = canonicalProfileId - ? new Set([ - canonicalProfileId, - ...listProfiles() - .filter((profile) => profile.mergedInto === canonicalProfileId) - .map((profile) => profile.id), - ]) - : undefined; - const recents = recentProfileIds - ? listProjectRecents(context.getRuntimeConfig(), recentProfileIds, projects) - : undefined; - const scopes = Array.isArray(client?.connect.scopes) ? client.connect.scopes : []; - if (authorizeOperatorScopesForRequiredScope(WRITE_SCOPE, scopes).allowed) { - respond(true, { projects, ...(recents ? { recents } : {}) }, undefined); - return; - } - // Project identity is read-safe; host paths and origins are placement - // details reserved for clients that can create sessions. - respond( - true, - { - projects: projects.map((project) => - project.agentId - ? { - id: project.id, - displayName: project.displayName, - source: project.source, - agentId: project.agentId, - } - : { - id: project.id, - displayName: project.displayName, - source: project.source, - }, - ), - ...(recents ? { recents: recents.filter((recent) => recent.kind === "project") } : {}), - }, - undefined, - ); - }, - "projects.register": async ({ params, respond }) => { - if (!assertValidParams(params, validateProjectsRegisterParams, "projects.register", respond)) { - return; - } - try { - respond( - true, - await registerProjectRegistry({ path: params.path, name: params.name }), - undefined, - ); - } catch (error) { - respond( - false, - undefined, - errorShape( - error instanceof ProjectCheckoutError - ? ErrorCodes.INVALID_REQUEST - : ErrorCodes.UNAVAILABLE, - formatErrorMessage(error), - ), - ); - } - }, - "projects.add": async ({ params, respond, context, signal }) => { - if (!assertValidParams(params, validateProjectsAddParams, "projects.add", respond)) { - return; - } - try { - respond( - true, - await materializeProjectClone( - { cfg: context.getRuntimeConfig(), gitUrl: params.gitUrl, name: params.name }, - { signal, token: githubApiToken() }, - ), - undefined, - ); - } catch (error) { - if (error instanceof ProjectCloneError) { - respond( - false, - undefined, - errorShape( - error.failure === "invalid_url" ? ErrorCodes.INVALID_REQUEST : ErrorCodes.UNAVAILABLE, - error.message, - { - details: { - code: GatewayErrorDetailCodes.PROJECT_CLONE_FAILED, - cause: error.failure, - }, - retryable: error.failure === "network" || error.failure === "clone_failed", - }, - ), - ); - return; - } - respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error))); - } - }, - "projects.searchRemote": async ({ params, respond }) => { - if ( - !assertValidParams( - params, - validateProjectsSearchRemoteParams, - "projects.searchRemote", - respond, - ) - ) { - return; - } - try { - respond(true, await searchRemoteProjects(params.query), undefined); - } catch { - respond( - false, - undefined, - errorShape(ErrorCodes.UNAVAILABLE, "GitHub project search is unavailable. Retry shortly.", { - retryable: true, - }), - ); - } - }, - "projects.remove": async ({ params, respond, context }) => { - if (!assertValidParams(params, validateProjectsRemoveParams, "projects.remove", respond)) { - return; - } - const project = resolveProjectRegistry(context.getRuntimeConfig(), params.id); - if (!project || project.source === "workspace") { - respond( - false, - undefined, - errorShape(ErrorCodes.INVALID_REQUEST, `unknown project id: ${params.id}`), - ); - return; - } - if (params.deleteCheckout) { - if (project.source !== "cloned") { - respond( - false, - undefined, - errorShape( - ErrorCodes.INVALID_REQUEST, - "Only projects cloned by the Gateway can delete their checkout.", - ), - ); - return; - } - const normalizedRoot = path.resolve(project.repoRoot); - const worktreeReference = listRegistryWorktrees(process.env).find( - (worktree) => !worktree.removedAt && path.resolve(worktree.repoRoot) === normalizedRoot, - ); - const sessionReference = Object.entries( - loadCombinedSessionStoreForGatewayCore(context.getRuntimeConfig(), { projection: "list" }) - .store, - ).find(([, entry]) => { - if (entry.archivedAt) { - return false; - } - const sessionRoot = entry.worktree?.repoRoot; - if (sessionRoot && path.resolve(sessionRoot) === normalizedRoot) { - return true; - } - const cwd = entry.spawnedCwd; - return Boolean( - cwd && - (path.resolve(cwd) === normalizedRoot || isPathInside(normalizedRoot, path.resolve(cwd))), - ); +function projectCandidatesToSummaries(candidates: readonly ProjectCandidate[]): ProjectSummary[] { + const groups = new Map(); + for (const candidate of candidates) { + const group: ProjectGroup = groups.get(candidate.fingerprint) ?? { + checkouts: new Map(), + lastUsedAt: candidate.lastUsedAt, + name: checkoutName(candidate.checkoutPath), + nameUsedAt: candidate.lastUsedAt, + }; + const checkout = group.checkouts.get(candidate.checkoutPath); + if (!checkout || candidate.lastUsedAt > checkout.lastUsedAt) { + group.checkouts.set(candidate.checkoutPath, { + path: candidate.checkoutPath, + lastUsedAt: candidate.lastUsedAt, }); - if (worktreeReference || sessionReference) { - const reference = worktreeReference - ? `managed worktree ${worktreeReference.name}` - : `session ${sessionReference?.[0]}`; - respond( - false, - undefined, - errorShape( - ErrorCodes.INVALID_REQUEST, - `Project checkout is still referenced by ${reference}. Remove that reference before deleting the checkout.`, + } + group.lastUsedAt = Math.max(group.lastUsedAt, candidate.lastUsedAt); + if (candidate.lastUsedAt > group.nameUsedAt) { + group.name = checkoutName(candidate.checkoutPath); + group.nameUsedAt = candidate.lastUsedAt; + } + if (!group.originUrl && candidate.originUrl) { + group.originUrl = candidate.originUrl; + } + groups.set(candidate.fingerprint, group); + } + return [...groups.values()] + .toSorted( + (left, right) => right.lastUsedAt - left.lastUsedAt || left.name.localeCompare(right.name), + ) + .slice(0, PROJECTS_LIST_DEFAULT_LIMIT) + .map((group) => { + const summary: ProjectSummary = { + name: group.name, + checkouts: [...group.checkouts.values()] + .toSorted( + (left, right) => + right.lastUsedAt - left.lastUsedAt || left.path.localeCompare(right.path), + ) + .slice(0, PROJECTS_LIST_MAX_CHECKOUTS_PER_PROJECT) + .map((checkout) => ({ runnerId: "gateway", path: checkout.path })), + lastUsedAt: group.lastUsedAt, + }; + if (group.originUrl) { + const originUrl = sanitizePublicOriginUrl(group.originUrl); + if (originUrl) { + summary.originUrl = originUrl; + } + } + return summary; + }); +} + +async function listObservedProjects( + service: ProjectWorktreeService, + context: Parameters[0]["context"], + client: Parameters[0]["client"], +): Promise { + const { store } = loadCombinedSessionStoreForGatewayCore(context.getRuntimeConfig(), { + projection: "list", + }); + const rawCandidates: RawProjectCandidate[] = []; + const visibilityFilter = createSessionListEntryFilter({ client }); + const canSeeAll = !visibilityFilter; + for (const [sessionKey, entry] of Object.entries(store)) { + if (visibilityFilter && !visibilityFilter(sessionKey, entry)) { + continue; + } + const checkoutPath = entry.execCwd?.trim(); + if (checkoutPath && !entry.execNode?.trim()) { + retainNewestRawProjectCandidate(rawCandidates, { + kind: "session", + checkoutPath, + lastUsedAt: entry.updatedAt, + }); + } + } + for (const worktree of service.listRegistryRecords()) { + if (worktree.removedAt !== undefined) { + continue; + } + if (!canSeeAll) { + // Session-owned worktrees use their canonical session key as ownerId, so the same + // visibility policy that admitted the session also owns its managed checkout. + const ownerId = worktree.ownerKind === "session" ? worktree.ownerId?.trim() : undefined; + const ownerEntry = ownerId ? store[ownerId] : undefined; + if (!ownerId || !ownerEntry || !visibilityFilter?.(ownerId, ownerEntry)) { + continue; + } + } + retainNewestRawProjectCandidate(rawCandidates, { + kind: "worktree", + checkoutPath: worktree.path, + fingerprint: worktree.repoFingerprint, + lastUsedAt: worktree.lastActiveAt, + repoRoot: worktree.repoRoot, + }); + } + + const candidates: ProjectCandidate[] = []; + type RepositoryIdentity = Awaited< + ReturnType + >; + const identities = new Map>(); + let identityProbeCount = 0; + const resolveIdentity = (checkoutPath: string) => { + const existing = identities.get(checkoutPath); + if (existing) { + return existing; + } + if (identityProbeCount >= PROJECTS_LIST_MAX_IDENTITY_PROBES) { + return undefined; + } + identityProbeCount += 1; + const identity = Promise.resolve().then(() => service.resolveRepositoryIdentity(checkoutPath)); + identities.set(checkoutPath, identity); + return identity; + }; + + // The buffer is already newest-first, so probes always go to the retained top-K candidates. + for (const raw of rawCandidates) { + if (raw.kind === "worktree") { + let originUrl: string | undefined; + const pendingIdentity = resolveIdentity(raw.repoRoot); + try { + const identity = pendingIdentity ? await pendingIdentity : undefined; + originUrl = identity?.originUrl || undefined; + } catch { + // The registry fingerprint and checkout path remain authoritative if the source checkout + // disappears after the managed worktree record was written. + } + candidates.push({ + checkoutPath: raw.checkoutPath, + fingerprint: raw.fingerprint, + lastUsedAt: raw.lastUsedAt, + ...(originUrl ? { originUrl } : {}), + }); + continue; + } + const pendingIdentity = resolveIdentity(raw.checkoutPath); + if (!pendingIdentity) { + continue; + } + try { + const identity = await pendingIdentity; + candidates.push({ + checkoutPath: identity.checkoutRoot, + fingerprint: identity.fingerprint, + lastUsedAt: raw.lastUsedAt, + ...(identity.originUrl ? { originUrl: identity.originUrl } : {}), + }); + } catch { + // Plain folders remain available through the existing folder picker. + } + } + + // M5: merge operator-enabled device checkout advertisements at this seam. + return projectCandidatesToSummaries(candidates); +} + +export function createProjectsHandlers(service: ProjectWorktreeService): GatewayRequestHandlers { + return { + "projects.list": async ({ params, respond, context, client }) => { + if (!assertValidParams(params, validateProjectsListParams, "projects.list", respond)) { + return; + } + const registryProjects = listProjectRegistry(context.getRuntimeConfig()); + const projects = registryProjects.map(sanitizeProjectRecord); + const profileId = client?.authenticatedUserProfile?.profileId; + const canonicalProfileId = profileId + ? (resolveUserProfileId(profileId) ?? profileId) + : undefined; + const recentProfileIds = canonicalProfileId + ? new Set([ + canonicalProfileId, + ...listProfiles() + .filter((profile) => profile.mergedInto === canonicalProfileId) + .map((profile) => profile.id), + ]) + : undefined; + const recents = recentProfileIds + ? listProjectRecents(context.getRuntimeConfig(), recentProfileIds, registryProjects) + : undefined; + const scopes = Array.isArray(client?.connect.scopes) ? client.connect.scopes : []; + const canWrite = authorizeOperatorScopesForRequiredScope(WRITE_SCOPE, scopes).allowed; + if (params.includeObserved && canWrite) { + try { + const observedProjects = await listObservedProjects(service, context, client); + respond(true, { projects, ...(recents ? { recents } : {}), observedProjects }, undefined); + } catch (error) { + respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error))); + } + return; + } + if (canWrite) { + respond(true, { projects, ...(recents ? { recents } : {}) }, undefined); + return; + } + // Project identity is read-safe; host paths, origins, folders, and observed checkouts are + // placement details reserved for clients that can create sessions. + respond( + true, + { + projects: projects.map((project) => + project.agentId + ? { + id: project.id, + displayName: project.displayName, + source: project.source, + agentId: project.agentId, + } + : { + id: project.id, + displayName: project.displayName, + source: project.source, + }, ), - ); + ...(recents ? { recents: recents.filter((recent) => recent.kind === "project") } : {}), + }, + undefined, + ); + }, + "projects.register": async ({ params, respond }) => { + if ( + !assertValidParams(params, validateProjectsRegisterParams, "projects.register", respond) + ) { return; } try { - await deleteClonedProjectCheckout(project); + respond( + true, + sanitizeProjectRecord( + await registerProjectRegistry({ path: params.path, name: params.name }), + ), + undefined, + ); } catch (error) { - respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error))); + respond( + false, + undefined, + errorShape( + error instanceof ProjectCheckoutError + ? ErrorCodes.INVALID_REQUEST + : ErrorCodes.UNAVAILABLE, + formatErrorMessage(error), + ), + ); + } + }, + "projects.add": async ({ params, respond, context, signal }) => { + if (!assertValidParams(params, validateProjectsAddParams, "projects.add", respond)) { return; } - } - if (!removeProjectRegistry(params.id)) { - respond( - false, - undefined, - errorShape(ErrorCodes.INVALID_REQUEST, `unknown project id: ${params.id}`), - ); - return; - } - respond(true, { removed: true }, undefined); - }, -}; + try { + respond( + true, + await materializeProjectClone( + { cfg: context.getRuntimeConfig(), gitUrl: params.gitUrl, name: params.name }, + { signal, token: githubApiToken() }, + ), + undefined, + ); + } catch (error) { + if (error instanceof ProjectCloneError) { + respond( + false, + undefined, + errorShape( + error.failure === "invalid_url" ? ErrorCodes.INVALID_REQUEST : ErrorCodes.UNAVAILABLE, + error.message, + { + details: { + code: GatewayErrorDetailCodes.PROJECT_CLONE_FAILED, + cause: error.failure, + }, + retryable: error.failure === "network" || error.failure === "clone_failed", + }, + ), + ); + return; + } + respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error))); + } + }, + "projects.searchRemote": async ({ params, respond }) => { + if ( + !assertValidParams( + params, + validateProjectsSearchRemoteParams, + "projects.searchRemote", + respond, + ) + ) { + return; + } + try { + respond(true, await searchRemoteProjects(params.query), undefined); + } catch { + respond( + false, + undefined, + errorShape( + ErrorCodes.UNAVAILABLE, + "GitHub project search is unavailable. Retry shortly.", + { retryable: true }, + ), + ); + } + }, + "projects.remove": async ({ params, respond, context }) => { + if (!assertValidParams(params, validateProjectsRemoveParams, "projects.remove", respond)) { + return; + } + const project = resolveProjectRegistry(context.getRuntimeConfig(), params.id); + if (!project || project.source === "workspace") { + respond( + false, + undefined, + errorShape(ErrorCodes.INVALID_REQUEST, `unknown project id: ${params.id}`), + ); + return; + } + if (params.deleteCheckout) { + if (project.source !== "cloned") { + respond( + false, + undefined, + errorShape( + ErrorCodes.INVALID_REQUEST, + "Only projects cloned by the Gateway can delete their checkout.", + ), + ); + return; + } + const normalizedRoot = path.resolve(project.repoRoot); + const worktreeReference = listRegistryWorktrees(process.env).find( + (worktree) => !worktree.removedAt && path.resolve(worktree.repoRoot) === normalizedRoot, + ); + const sessionReference = Object.entries( + loadCombinedSessionStoreForGatewayCore(context.getRuntimeConfig(), { + projection: "list", + }).store, + ).find(([, entry]) => { + if (entry.archivedAt) { + return false; + } + const sessionRoot = entry.worktree?.repoRoot; + if (sessionRoot && path.resolve(sessionRoot) === normalizedRoot) { + return true; + } + const cwd = entry.spawnedCwd; + return Boolean( + cwd && + (path.resolve(cwd) === normalizedRoot || + isPathInside(normalizedRoot, path.resolve(cwd))), + ); + }); + if (worktreeReference || sessionReference) { + const reference = worktreeReference + ? `managed worktree ${worktreeReference.name}` + : `session ${sessionReference?.[0]}`; + respond( + false, + undefined, + errorShape( + ErrorCodes.INVALID_REQUEST, + `Project checkout is still referenced by ${reference}. Remove that reference before deleting the checkout.`, + ), + ); + return; + } + try { + await deleteClonedProjectCheckout(project); + } catch (error) { + respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error))); + return; + } + } + if (!removeProjectRegistry(params.id)) { + respond( + false, + undefined, + errorShape(ErrorCodes.INVALID_REQUEST, `unknown project id: ${params.id}`), + ); + return; + } + respond(true, { removed: true }, undefined); + }, + }; +} + +export const projectsHandlers = createProjectsHandlers(managedWorktrees); diff --git a/ui/src/e2e/new-session-page.operator-scopes.e2e.test.ts b/ui/src/e2e/new-session-page.operator-scopes.e2e.test.ts index 19ad02291a58..f78406a9c9e6 100644 --- a/ui/src/e2e/new-session-page.operator-scopes.e2e.test.ts +++ b/ui/src/e2e/new-session-page.operator-scopes.e2e.test.ts @@ -10,7 +10,13 @@ const suite = createNewSessionPageE2eSuite(); async function openDraft( operatorScopes: string[], - featureMethods = ["chat.metadata", "chat.startup", "sessions.create", "sessions.dispatch"], + featureMethods = [ + "chat.metadata", + "chat.startup", + "projects.list", + "sessions.create", + "sessions.dispatch", + ], ) { const context = await suite.browser.newContext({ locale: "en-US", @@ -22,6 +28,7 @@ async function openDraft( featureMethods, operatorScopes, methodResponses: { + "projects.list": { projects: [] }, "sessions.create": { key: "agent:main:operator-scope-proof", runStarted: true }, }, }); @@ -32,7 +39,10 @@ async function openDraft( suite.define(() => { it("keeps read-scoped operators out of new-session entry and submission paths", async () => { - const { context, gateway, page } = await openDraft(["operator.read"]); + const { context, gateway, page } = await openDraft( + ["operator.read"], + ["chat.metadata", "chat.startup", "projects.list", "sessions.create", "sessions.dispatch"], + ); try { const sidebarCreate = page.locator(".sidebar-brand__new-thread"); const submit = page.getByRole("button", { name: "Start session" }); @@ -45,6 +55,9 @@ suite.define(() => { "This action requires operator.admin access.", ); await submit.click({ force: true }); + const projectRequests = await gateway.getRequests("projects.list"); + expect(projectRequests).toHaveLength(1); + expect(projectRequests[0]?.params).toEqual({}); expect(await gateway.getRequests("sessions.create")).toHaveLength(0); } finally { await context.close(); @@ -54,6 +67,9 @@ suite.define(() => { it("allows write-scoped normal creation while keeping incognito admin-only", async () => { const { context, gateway, page } = await openDraft(["operator.read", "operator.write"]); try { + await expect(gateway.waitForRequest("projects.list")).resolves.toMatchObject({ + params: {}, + }); const submit = page.getByRole("button", { name: "Start session" }); const incognito = page.getByRole("switch", { name: "Incognito" }); diff --git a/ui/src/e2e/new-session-page.projects-places.e2e.test.ts b/ui/src/e2e/new-session-page.projects-places.e2e.test.ts new file mode 100644 index 000000000000..f98b5d2c5759 --- /dev/null +++ b/ui/src/e2e/new-session-page.projects-places.e2e.test.ts @@ -0,0 +1,816 @@ +import { expect, it } from "vitest"; +import { + EXEC_ONLY_PICKED, + NODE_HOME, + NODE_PICKED, + NODE_UNC, + SESSION_LIST_DEFAULTS, + WORKSPACE, + captureProjectUiProof, + captureUiProof, + createNewSessionPageE2eSuite, + createdSessionListResult, + installMockGateway, + pollLocatorText, + prepareProjectUiProof, + replaceGatewayClient, +} from "./new-session-page.test-support.ts"; + +const suite = createNewSessionPageE2eSuite(); +const gatewayEnvironment = { + id: "gateway", + type: "local", + status: "available", +}; +const deviceEnvironment = (nodeId: string) => ({ + id: `node:${nodeId}`, + type: "node", + status: "available", +}); + +suite.define(() => { + it("registers a Git checkout from Browse and selects the refreshed project", async () => { + await prepareProjectUiProof(); + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const repoRoot = "/recorded/openclaw"; + const registeredProject = { + id: "recorded-openclaw", + displayName: "openclaw", + repoRoot, + originUrl: "https://github.com/openclaw/openclaw.git", + source: "registered", + }; + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + featureMethods: [ + "chat.metadata", + "chat.startup", + "fs.listDir", + "projects.list", + "projects.register", + "sessions.create", + "worktrees.branches", + ], + methodResponses: { + "projects.list": { + sequence: [{ projects: [] }, { projects: [registeredProject] }], + }, + "projects.register": registeredProject, + "fs.listDir": { + cases: [ + { + match: { path: WORKSPACE }, + response: { path: WORKSPACE, home: "/home/peter", entries: [] }, + }, + { + match: { path: repoRoot }, + response: { path: repoRoot, parent: "/recorded", home: "/home/peter", entries: [] }, + }, + ], + }, + "worktrees.branches": { + branches: [{ kind: "local", name: "main" }], + defaultBranch: "main", + repositoryStatus: "git", + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("projects.list"); + const trigger = page.locator("#new-session-place-trigger"); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await trigger.click(); + await place.getByRole("button", { name: "Browse folders" }).click(); + const pathInput = page.locator("input.new-session-page__browser-path"); + await pathInput.fill(repoRoot); + await pathInput.press("Enter"); + const register = place.getByRole("button", { name: "Register as project" }); + await register.waitFor(); + await captureProjectUiProof(page, "project-register-action.png"); + await register.click(); + + const request = await gateway.waitForRequest("projects.register"); + expect(request.params).toEqual({ path: repoRoot }); + await expect.poll(async () => (await gateway.getRequests("projects.list")).length).toBe(2); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe("openclaw"); + expect(await trigger.getAttribute("data-project-id")).toBe("recorded-openclaw"); + } finally { + await context.close(); + } + }); + + it("handles a legacy projects-only response for write-scoped operators", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + operatorScopes: ["operator.read", "operator.write"], + featureMethods: ["chat.metadata", "chat.startup", "projects.list", "sessions.create"], + methodResponses: { "projects.list": { projects: [] } }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("projects.list"); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await page.locator("#new-session-place-trigger").click(); + await place.getByText("Projects", { exact: true }).waitFor(); + await place + .getByText("Admins can register projects from Browse folders", { exact: true }) + .waitFor(); + expect(await place.getByRole("button", { name: "Register as project" }).count()).toBe(0); + } finally { + await context.close(); + } + }); + + it("hides the destination axis when the Gateway is the only place", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + methodResponses: { + "node.list": { nodes: [] }, + "environments.list": { + environments: [gatewayEnvironment], + profiles: [], + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("node.list"); + const trigger = page.locator("#new-session-place-trigger"); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe("openclaw"); + await trigger.click(); + const place = page.locator("wa-popover.new-session-page__place-popover"); + expect(await place.getByText("Places", { exact: true }).count()).toBe(0); + await place.getByText("Runs on Gateway · local", { exact: true }).waitFor(); + } finally { + await context.close(); + } + }); + + it("uses advertised system info for Gateway place labels", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + featureMethods: ["chat.metadata", "chat.startup", "sessions.create", "system.info"], + methodResponses: { + "system.info": { + machineName: "Peters-Mac-Studio", + hostname: "peters-mac-studio.local", + platform: "darwin", + }, + "node.list": { + nodes: [ + { + nodeId: "macbook", + displayName: "MacBook", + connected: true, + commands: ["system.run"], + }, + ], + }, + "environments.list": { + environments: [gatewayEnvironment, deviceEnvironment("macbook")], + profiles: [], + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("system.info"); + const trigger = page.locator("#new-session-place-trigger"); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe( + "openclaw · Gateway · Peters-Mac-Studio", + ); + await trigger.click(); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await place.getByRole("button", { name: "Gateway · Peters-Mac-Studio" }).waitFor(); + await place.getByRole("button", { name: "Browse folders" }).click(); + await expect + .poll(() => + page.locator("input.new-session-page__browser-path").getAttribute("placeholder"), + ) + .toBe("Gateway · Peters-Mac-Studio"); + + await gateway.setMethodResponse("node.list", { nodes: [] }); + const nodeRequests = (await gateway.getRequests("node.list")).length; + await replaceGatewayClient(page); + await expect + .poll(async () => (await gateway.getRequests("node.list")).length) + .toBeGreaterThan(nodeRequests); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe("openclaw"); + await trigger.click(); + await place.getByText("Runs on Gateway · Peters-Mac-Studio", { exact: true }).waitFor(); + } finally { + await context.close(); + } + }); + + it("shows live devices when the initial environment catalog is unavailable", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + methodResponses: { + "node.list": { + nodes: [ + { + nodeId: "fallback-device", + displayName: "Fallback device", + connected: true, + commands: ["system.run"], + }, + ], + }, + "environments.list": { + __mockError: { + code: "UNAVAILABLE", + message: "environment catalog unavailable", + }, + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("node.list"); + await gateway.waitForRequest("environments.list"); + await page.locator("#new-session-place-trigger").click(); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await place.getByText("Devices", { exact: true }).waitFor(); + await place.getByRole("button", { name: "Fallback device" }).waitFor(); + await captureUiProof(page, "04-catalog-unavailable-device-fallback.png"); + } finally { + await context.close(); + } + }); + + it("keeps the last environment catalog across a same-Gateway client refresh failure", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + methodResponses: { + "node.list": { + nodes: [ + { + nodeId: "stable-device", + displayName: "Stable device", + connected: true, + commands: ["system.run"], + }, + ], + }, + "environments.list": { + environments: [deviceEnvironment("stable-device")], + profiles: [], + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("environments.list"); + const trigger = page.locator("#new-session-place-trigger"); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await trigger.click(); + await place.getByRole("button", { name: "Stable device" }).waitFor(); + await page.keyboard.press("Escape"); + + await gateway.setMethodResponse("environments.list", { + __mockError: { + code: "UNAVAILABLE", + message: "environment refresh unavailable", + }, + }); + const environmentRequests = (await gateway.getRequests("environments.list")).length; + await replaceGatewayClient(page); + await expect + .poll(async () => (await gateway.getRequests("environments.list")).length) + .toBeGreaterThan(environmentRequests); + + await trigger.click(); + await place.getByRole("button", { name: "Stable device" }).waitFor(); + } finally { + await context.close(); + } + }); + + it("disambiguates duplicate node names without changing the selected chip", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + methodResponses: { + "node.list": { + nodes: [ + { + nodeId: "11111111aaaaaaaa", + displayName: "Mac Studio", + platform: "darwin", + modelIdentifier: "Mac14,12", + remoteIp: "192.168.1.11", + connected: true, + commands: ["system.run"], + }, + { + nodeId: "22222222bbbbbbbb", + displayName: "Mac Studio", + platform: "darwin", + modelIdentifier: "Mac15,14", + remoteIp: "192.168.1.12", + connected: true, + commands: ["system.run"], + }, + { + nodeId: "33333333cccccccc", + displayName: "iPhone", + platform: "iOS 26.4", + deviceFamily: "iPhone", + modelIdentifier: "iPhone17,2", + remoteIp: "192.168.1.30", + connected: true, + commands: ["system.run"], + }, + ], + }, + "environments.list": { + environments: [ + gatewayEnvironment, + { id: "node:11111111aaaaaaaa", type: "node", status: "available" }, + deviceEnvironment("22222222bbbbbbbb"), + deviceEnvironment("33333333cccccccc"), + ], + profiles: [], + }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("node.list"); + const trigger = page.locator("#new-session-place-trigger"); + await trigger.click(); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await place + .locator(".new-session-page__menu-title") + .getByText("This gateway", { exact: true }) + .waitFor(); + await place.getByText("Devices", { exact: true }).waitFor(); + const first = page.locator('[data-value="node:11111111aaaaaaaa"]'); + const second = page.locator('[data-value="node:22222222bbbbbbbb"]'); + const phone = page.locator('[data-value="node:33333333cccccccc"]'); + await pollLocatorText(first.locator(".session-menu__sub")).toBe("Mac14,12"); + await pollLocatorText(second.locator(".session-menu__sub")).toBe("Mac15,14"); + await pollLocatorText(phone.locator(".session-menu__text")).toBe("iPhone"); + expect(await first.locator(".session-menu__icon svg").count()).toBe(1); + expect(await second.locator(".session-menu__icon svg").count()).toBe(1); + expect(await phone.locator(".session-menu__icon svg").count()).toBe(1); + expect(await first.getAttribute("title")).toBe("macOS · Mac14,12 · 192.168.1.11"); + expect(await second.getAttribute("title")).toContain("192.168.1.12"); + await captureUiProof(page, "03-legacy-device-picker.png"); + await second.click(); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe( + "Agent workspace · Mac Studio", + ); + expect(await trigger.textContent()).not.toContain("Mac15,14"); + expect(await trigger.textContent()).not.toContain("192.168.1.12"); + } finally { + await context.close(); + } + }); + + it("keeps and disambiguates recent locations with the same basename", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + methodResponses: { + "node.list": { nodes: [] }, + "environments.list": { environments: [], profiles: [] }, + "sessions.list": { + count: 2, + defaults: SESSION_LIST_DEFAULTS, + path: "", + sessions: [ + { key: "agent:main:a", kind: "direct", updatedAt: 2, execCwd: "/a/openclaw" }, + { key: "agent:main:b", kind: "direct", updatedAt: 1, execCwd: "/b/openclaw" }, + ], + ts: Date.now(), + }, + "sessions.create": { key: "agent:main:recent-collision" }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("node.list"); + const trigger = page.locator("#new-session-place-trigger"); + await trigger.click(); + const first = page.locator('[data-value="recent::/a/openclaw"]'); + const second = page.locator('[data-value="recent::/b/openclaw"]'); + await first.waitFor(); + await second.waitFor(); + await pollLocatorText(first.locator(".session-menu__sub")).toBe("a"); + await pollLocatorText(second.locator(".session-menu__sub")).toBe("b"); + const recentValues = await page + .locator('[data-value^="recent::"]') + .evaluateAll((items) => items.map((item) => item.getAttribute("data-value"))); + expect(recentValues).toEqual(["recent::/a/openclaw", "recent::/b/openclaw"]); + await second.click(); + await page.locator(".new-session-page__message").fill("continue in work checkout"); + await page.getByRole("button", { name: "Start session" }).click(); + const create = await gateway.waitForRequest("sessions.create"); + expect(create.params).toMatchObject({ + cwd: "/b/openclaw", + message: "continue in work checkout", + }); + } finally { + await context.close(); + } + }); + + it("applies a recent folder and node as one place", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspace: WORKSPACE, + workspaceGit: true, + methodResponses: { + "node.list": { + nodes: [ + { + nodeId: "macbook", + displayName: "MacBook", + connected: true, + commands: ["system.run", "fs.listDir"], + }, + ], + }, + "environments.list": { + environments: [gatewayEnvironment, deviceEnvironment("macbook")], + profiles: [], + }, + "sessions.list": { + count: 2, + defaults: SESSION_LIST_DEFAULTS, + path: "", + sessions: [ + { + key: "agent:main:recent-node", + kind: "direct", + updatedAt: 2, + execCwd: NODE_PICKED, + execNode: "macbook", + }, + { + key: "agent:main:workspace", + kind: "direct", + updatedAt: 1, + execCwd: WORKSPACE, + }, + ], + ts: Date.now(), + }, + "sessions.create": { key: "agent:main:recent-place" }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("node.list"); + const trigger = page.locator("#new-session-place-trigger"); + await trigger.click(); + await page + .locator("wa-popover.new-session-page__place-popover") + .getByRole("button", { name: "Projects · MacBook", exact: true }) + .click(); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe( + "Projects · MacBook", + ); + + await page.locator(".new-session-page__message").fill("continue on the recent node"); + await page.getByRole("button", { name: "Start session" }).click(); + const create = await gateway.waitForRequest("sessions.create"); + expect(create.params).toMatchObject({ + cwd: NODE_PICKED, + execNode: "macbook", + message: "continue on the recent node", + }); + } finally { + await context.close(); + } + }); + it("runs directly in a custom non-Git Gateway folder", async () => { + const context = await suite.browser.newContext({ locale: "en-US", serviceWorkers: "block" }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspaceGit: true, + methodResponses: { + "agents.list": { + agents: [ + { + id: "main", + identity: { name: "Main" }, + name: "Main", + workspace: WORKSPACE, + workspaceGit: true, + }, + ], + defaultId: "main", + mainKey: "main", + scope: "agent", + }, + "environments.list": { + environments: [gatewayEnvironment], + profiles: [{ id: "aws", providerId: "crabbox" }], + }, + "fs.listDir": { path: WORKSPACE, home: "/home/peter", entries: [] }, + "worktrees.branches": { + cases: [ + { + match: { repoRoot: WORKSPACE }, + response: { + branches: [{ kind: "local", name: "main" }], + defaultBranch: "main", + repositoryStatus: "git", + }, + }, + { + match: { repoRoot: "/home" }, + response: { branches: [], repositoryStatus: "not_git" }, + }, + ], + }, + "sessions.create": { key: "agent:main:plain-folder" }, + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await gateway.waitForRequest("environments.list"); + const trigger = page.locator("#new-session-place-trigger"); + const place = page.locator("wa-popover.new-session-page__place-popover"); + await trigger.click(); + await place.getByRole("button", { name: "Browse folders" }).click(); + await page.locator("input.new-session-page__browser-path").fill("/home"); + await page.getByRole("button", { name: "Use this folder" }).click(); + await expect + .poll(async () => (await gateway.getRequests("worktrees.branches")).at(-1)?.params) + .toEqual({ repoRoot: "/home", includeRepositoryStatus: true }); + await pollLocatorText(trigger.locator(".new-session-page__trigger-label")).toBe( + "home · Gateway · local", + ); + + await trigger.click(); + expect(await place.getByRole("button", { name: "Worktree" }).count()).toBe(0); + await place + .locator(".new-session-page__menu-title") + .getByText("This gateway", { exact: true }) + .waitFor(); + await place.getByText("Cloud", { exact: true }).waitFor(); + const cloud = place.getByRole("button", { name: "Cloud · aws" }); + expect(await cloud.isDisabled()).toBe(true); + expect(await cloud.getAttribute("title")).toBe("Cloud workers require a managed worktree"); + await page.keyboard.press("Escape"); + + await page.locator(".new-session-page__message").fill("clone and inspect this project"); + await page.getByRole("button", { name: "Start session" }).click(); + const create = await gateway.waitForRequest("sessions.create"); + expect(create.params).toMatchObject({ + agentId: "main", + cwd: "/home", + message: "clone and inspect this project", + }); + expect(create.params).not.toHaveProperty("worktree"); + expect(create.params).not.toHaveProperty("worktreeBaseRef"); + } finally { + await context.close(); + } + }); + + it("browses capable nodes and accepts manual paths for exec-only nodes", async () => { + const context = await suite.browser.newContext({ + locale: "en-US", + serviceWorkers: "block", + viewport: { height: 900, width: 1280 }, + }); + const page = await context.newPage(); + const gateway = await installMockGateway(page, { + workspaceGit: true, + methodResponses: { + "agents.list": { + agents: [ + { + id: "main", + identity: { name: "Main" }, + name: "Main", + workspace: WORKSPACE, + workspaceGit: true, + }, + { + id: "research", + identity: { name: "Research" }, + name: "Research", + workspace: "/home/peter/research", + workspaceGit: true, + }, + ], + defaultId: "main", + mainKey: "main", + scope: "agent", + }, + "node.list": { + nodes: [ + { + nodeId: "macbook", + displayName: "MacBook", + connected: true, + commands: ["system.run", "fs.listDir"], + }, + { + nodeId: "old-node", + displayName: "Old node", + connected: true, + commands: ["system.run"], + }, + { + nodeId: "offline-node", + displayName: "Offline node", + connected: false, + commands: ["system.run", "fs.listDir"], + }, + ], + }, + "environments.list": { + environments: [ + gatewayEnvironment, + deviceEnvironment("macbook"), + deviceEnvironment("old-node"), + deviceEnvironment("offline-node"), + ], + profiles: [], + }, + "fs.listDir": { + cases: [ + { + match: { nodeId: "macbook", path: NODE_UNC }, + response: { + path: NODE_UNC, + parent: "\\\\server\\share", + home: "C:\\Users\\peter", + entries: [], + }, + }, + { + match: { nodeId: "macbook", path: NODE_PICKED }, + response: { + path: NODE_PICKED, + parent: NODE_HOME, + home: NODE_HOME, + entries: [], + }, + }, + { + match: { nodeId: "macbook" }, + response: { + path: NODE_HOME, + home: NODE_HOME, + entries: [{ name: "Projects", path: NODE_PICKED }], + }, + }, + ], + }, + "sessions.create": { key: "agent:main:node-draft-e2e" }, + "sessions.list": createdSessionListResult("agent:main:node-draft-e2e"), + }, + }); + + try { + await page.goto(`${suite.server.baseUrl}new`); + await page.locator(".new-session-page__message").waitFor(); + const placeSelect = page.locator("wa-popover.new-session-page__place-popover"); + const placeTrigger = page.locator("#new-session-place-trigger"); + const placeLabel = placeTrigger.locator(".new-session-page__trigger-label"); + const browserEntries = page.locator(".new-session-page__browser-list"); + + // Pick the node from Devices. + await placeTrigger.click(); + await placeSelect + .locator(".new-session-page__menu-title") + .getByText("This gateway", { exact: true }) + .waitFor(); + await placeSelect.getByText("Devices", { exact: true }).waitFor(); + await placeSelect.getByRole("button", { name: "MacBook" }).click(); + await pollLocatorText(placeLabel).toBe("Agent workspace · MacBook"); + // Node sessions cannot use managed worktrees, so the menu drops the item. + await placeTrigger.click(); + expect(await placeSelect.getByRole("button", { name: "Worktree" }).count()).toBe(0); + await page.keyboard.press("Escape"); + + // Manual path entry in the browser head preserves UNC paths; these + // cannot be rediscovered by starting at the node home directory. + await placeTrigger.click(); + await placeSelect.getByRole("button", { name: "Browse folders" }).click(); + const pathInput = page.locator("input.new-session-page__browser-path"); + await expect.poll(() => pathInput.inputValue()).toBe(NODE_HOME); + await pathInput.fill(NODE_UNC); + await pathInput.press("Enter"); + await expect.poll(() => pathInput.inputValue()).toBe(NODE_UNC); + // Escape returns to the picker root without applying or closing it. + await page.keyboard.press("Escape"); + await expect + .poll(() => + placeSelect.evaluate((element) => (element as HTMLElement & { open: boolean }).open), + ) + .toBe(true); + await placeSelect + .locator(".new-session-page__menu-title") + .getByText("This gateway", { exact: true }) + .waitFor(); + + // Destination selection stays grouped by place; browsing is fixed to the current target. + await placeSelect.getByRole("button", { name: "Gateway · local" }).click(); + await pollLocatorText(placeLabel).toBe("openclaw · Gateway · local"); + await placeTrigger.click(); + expect(await placeSelect.getByRole("button", { name: "Offline node" }).count()).toBe(0); + await placeSelect.getByRole("button", { name: "MacBook" }).click(); + await placeTrigger.click(); + await placeSelect.getByRole("button", { name: "Browse folders" }).click(); + await browserEntries.getByRole("button", { name: "Projects" }).click(); + await page.getByRole("button", { name: "Use this folder" }).click(); + + // Using a node folder retargets the draft to that node. + await pollLocatorText(placeLabel).toBe("Projects · MacBook"); + + // A node cwd belongs to the selected agent's draft and must not leak + // across an agent change, even though the execution node stays selected. + const agentPicker = page.locator(".new-session-page__select--agent openclaw-agent-select"); + await agentPicker.locator(".agent-select__trigger").click(); + await agentPicker + .locator("wa-dropdown-item[data-agent-option]") + .filter({ hasText: "Research" }) + .click(); + await page.getByRole("heading", { name: "Research" }).waitFor(); + await pollLocatorText(placeLabel).toBe("Agent workspace · MacBook"); + + // Clearing the path applies the node's default directory (empty folder), + // the state the replaced clearable folder textbox could express. + await placeTrigger.click(); + await placeSelect.getByRole("button", { name: "Browse folders" }).click(); + await expect.poll(() => pathInput.inputValue()).toBe(NODE_HOME); + await pathInput.fill(""); + await page.getByRole("button", { name: "Use this folder" }).click(); + await pollLocatorText(placeLabel).toBe("Agent workspace · MacBook"); + + // Browse back to the custom folder, then retarget to the exec-only node + // with a manual absolute path for the final create assertion. + await placeTrigger.click(); + await placeSelect.getByRole("button", { name: "Browse folders" }).click(); + await browserEntries.getByRole("button", { name: "Projects" }).click(); + await page.getByRole("button", { name: "Use this folder" }).click(); + await pollLocatorText(placeLabel).toBe("Projects · MacBook"); + + await placeTrigger.click(); + await placeSelect.getByRole("button", { name: "Old node" }).click(); + await placeTrigger.click(); + await placeSelect.getByRole("button", { name: "Browse folders" }).click(); + await expect.poll(() => pathInput.inputValue()).toBe(""); + await pathInput.fill(EXEC_ONLY_PICKED); + await pathInput.press("Enter"); + expect( + (await gateway.getRequests("fs.listDir")).filter( + (request) => (request.params as { nodeId?: string } | undefined)?.nodeId === "old-node", + ), + ).toHaveLength(0); + await page.getByRole("button", { name: "Use this folder" }).click(); + await pollLocatorText(placeLabel).toBe("repo · Old node"); + + await page.locator(".new-session-page__message").fill("inspect the remote checkout"); + await page.getByRole("button", { name: "Start session" }).click(); + const createRequest = await gateway.waitForRequest("sessions.create"); + expect(createRequest.params).toMatchObject({ + agentId: "research", + message: "inspect the remote checkout", + execNode: "old-node", + cwd: EXEC_ONLY_PICKED, + }); + expect(createRequest.params).not.toHaveProperty("worktree"); + } finally { + await context.close(); + } + }); +}); diff --git a/ui/src/e2e/new-session-page.workspace-validation.e2e.test.ts b/ui/src/e2e/new-session-page.workspace-validation.e2e.test.ts index 06f1abeaa377..c70471f80942 100644 --- a/ui/src/e2e/new-session-page.workspace-validation.e2e.test.ts +++ b/ui/src/e2e/new-session-page.workspace-validation.e2e.test.ts @@ -46,6 +46,14 @@ function branchList(name = "main") { }; } +function deviceEnvironment(nodeId: string) { + return { + id: `node:${nodeId}`, + type: "node", + status: "available", + }; +} + async function withNewSessionPage( options: BrowserContextOptions, run: (page: Page) => Promise, @@ -295,12 +303,17 @@ suite.define(() => { }, ], }, + "environments.list": { + environments: [deviceEnvironment("old-device")], + profiles: [], + }, "worktrees.branches": branchList(), "sessions.create": { key: "agent:main:validated-device" }, }, }); await page.goto(`${suite.server.baseUrl}new`); await gateway.waitForRequest("node.list"); + await gateway.waitForRequest("environments.list"); const placeSelect = page.locator("wa-popover.new-session-page__place-popover"); await page.locator("#new-session-place-trigger").click(); await placeSelect.getByRole("button", { name: "Old device" }).click(); @@ -343,12 +356,17 @@ suite.define(() => { }, ], }, + "environments.list": { + environments: [deviceEnvironment("old-device")], + profiles: [], + }, "worktrees.branches": branchList("alpha"), }, }); await page.goto(`${suite.server.baseUrl}new`); await page.getByRole("heading", { name: "Original agent" }).waitFor(); await gateway.waitForRequest("node.list"); + await gateway.waitForRequest("environments.list"); await gateway.waitForRequest("worktrees.branches"); const message = page.locator(".new-session-page__message"); @@ -379,9 +397,14 @@ suite.define(() => { }, ], }); + await gateway.setMethodResponse("environments.list", { + environments: [deviceEnvironment("new-device")], + profiles: [], + }); await gateway.setMethodResponse("worktrees.branches", branchList("beta")); const socketsBefore = await gateway.getSocketCount(); const nodesBefore = (await gateway.getRequests("node.list")).length; + const environmentsBefore = (await gateway.getRequests("environments.list")).length; const branchesBefore = (await gateway.getRequests("worktrees.branches")).length; await replaceGatewayClient(page); @@ -390,6 +413,9 @@ suite.define(() => { await expect .poll(async () => (await gateway.getRequests("node.list")).length) .toBe(nodesBefore + 1); + await expect + .poll(async () => (await gateway.getRequests("environments.list")).length) + .toBe(environmentsBefore + 1); await expect .poll(async () => (await gateway.getRequests("worktrees.branches")).length) .toBe(branchesBefore + 1); diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts index a8a8dc9e9f0d..7681cc675caa 100644 --- a/ui/src/i18n/locales/en.ts +++ b/ui/src/i18n/locales/en.ts @@ -699,6 +699,7 @@ export const en: TranslationMap = { agent: "Agent", where: "Where", gateway: "Gateway · local", + thisGateway: "This gateway", gatewayNamed: "Gateway · {name}", cloudWorker: "Cloud · {profile}", cloudWorkerProvider: "Cloud worker provider: {provider}", @@ -720,6 +721,7 @@ export const en: TranslationMap = { cloneProject: "Clone", cloningProject: "Cloning project…", registerProject: "Register as project", + cloud: "Cloud", recentFolders: "Recent", runsOn: "Runs on {place}", browse: "Browse folders", diff --git a/ui/src/pages/chat/chat-pane-base.ts b/ui/src/pages/chat/chat-pane-base.ts index 46b85af406d1..cdf6e9a51e5e 100644 --- a/ui/src/pages/chat/chat-pane-base.ts +++ b/ui/src/pages/chat/chat-pane-base.ts @@ -160,6 +160,7 @@ export abstract class ChatPaneBase extends OpenClawLightDomElement { @litState() protected headerRenameValue = ""; @litState() protected headerPlatform: string | null = null; @litState() protected headerCopiedAction: ChatPaneHeaderAction | null = null; + @litState() protected headerPlacementReclaimingKey: string | null = null; @litState() protected presencePayload: PresencePayload | undefined; @litState() protected sessionSharingStates = new Map(); protected readonly sessionParticipationTracker = new SessionParticipationTracker(); diff --git a/ui/src/pages/chat/chat-pane-context.ts b/ui/src/pages/chat/chat-pane-context.ts index ad685eeb8c89..5c6a3a7a95d5 100644 --- a/ui/src/pages/chat/chat-pane-context.ts +++ b/ui/src/pages/chat/chat-pane-context.ts @@ -1,3 +1,4 @@ +import type { GatewaySessionRow } from "../../api/types.ts"; import { invalidateAssistantIdentityCache } from "../../app/assistant-identity.ts"; import type { ApplicationContext, ApplicationGatewaySnapshot } from "../../app/context.ts"; import { hasOperatorAdminAccess } from "../../app/operator-access.ts"; @@ -22,6 +23,7 @@ import { import { invalidateChatAvatarCache } from "./chat-avatar.ts"; import { applyChatAgentsList, syncSelectedSessionMessageSubscription } from "./chat-history.ts"; import { ChatPaneLifecycle } from "./chat-pane-lifecycle.ts"; +import { reclaimChatPanePlacement } from "./chat-pane-placement.ts"; import { applySelectedSessionProjection } from "./chat-pane-state.ts"; import { resolveAssistantAttachmentAuthToken } from "./chat-pane-state.ts"; import { markQueuedChatSendsWaitingForReconnect } from "./chat-queue.ts"; @@ -53,6 +55,29 @@ export abstract class ChatPaneContext extends ChatPaneLifecycle { super.disconnectedCallback(); } + protected async reclaimHeaderPlacement(row: GatewaySessionRow): Promise { + const onReclaimingChange = (reclaimingKey: string | null) => { + // A later reclaim may take ownership before this request settles. Only + // the request that still owns the row may clear the pane's progress key. + if (reclaimingKey !== null || this.headerPlacementReclaimingKey === row.key) { + this.headerPlacementReclaimingKey = reclaimingKey; + } + }; + await reclaimChatPanePlacement({ + client: this.connectedClient, + connectionGeneration: this.connectionGeneration, + gatewaySnapshot: this.context.gateway.snapshot, + reclaimingKey: this.headerPlacementReclaimingKey, + row, + isCurrent: (client, generation) => + this.connectedClient === client && this.connectionGeneration === generation, + onReclaimingChange, + publishError: (error) => this.publishHeaderError(error), + refreshReplacement: (agentId) => this.context.sessions.refreshReplacement(agentId), + requestUpdate: () => this.requestUpdate(), + }); + } + protected applySessionsState(stateValue: ApplicationContext["sessions"]["state"]) { const state = this.state; if (!state) { diff --git a/ui/src/pages/chat/chat-pane-header.ts b/ui/src/pages/chat/chat-pane-header.ts index 41407f413b7b..ef43f5294eb1 100644 --- a/ui/src/pages/chat/chat-pane-header.ts +++ b/ui/src/pages/chat/chat-pane-header.ts @@ -25,6 +25,7 @@ import { import { normalizeOptionalString } from "../../lib/string-coerce.ts"; import { isActiveTask } from "../../lib/tasks/data.ts"; import { renderBoardViewSwitch } from "./board-session-surface.ts"; +import { resolveChatPanePlacement } from "./chat-pane-placement.ts"; import { ChatPaneSessionMenu } from "./chat-pane-session-menu.ts"; import { readChatSessionActionAccess } from "./chat-session-action-access.ts"; import { renderBackgroundTasksToggle } from "./components/chat-background-tasks-render.ts"; @@ -311,6 +312,11 @@ export abstract class ChatPaneHeader extends ChatPaneSessionMenu { onActivate: () => this.onSplitRight?.(this.paneId), }); } + const placement = resolveChatPanePlacement({ + gatewaySnapshot: this.context.gateway.snapshot, + reclaimingKey: this.headerPlacementReclaimingKey, + row, + }); return renderChatPaneHeader({ paneId: this.paneId, narrow: this.narrow, @@ -452,6 +458,7 @@ export abstract class ChatPaneHeader extends ChatPaneSessionMenu { .onAction=${(action: HeaderMenuAction) => this.handleHeaderSessionAction(action, row)} >` : nothing, + placementReclaimDisabledReason: placement.reclaimDisabledReason, nativeGateways: this.nativeGateways, gatewaysSnapshot: this.gatewaysSnapshot, onboarding: this.onboarding, @@ -474,6 +481,7 @@ export abstract class ChatPaneHeader extends ChatPaneSessionMenu { onOpenParentSession: (sessionKey) => { this.onPaneSessionChange?.(this.paneId, sessionKey); }, + onPlacementReclaim: () => row && void this.reclaimHeaderPlacement(row), onBranchSelect: (leafEntryId) => { const access = readChatSessionActionAccess( this.context.gateway.snapshot, diff --git a/ui/src/pages/chat/chat-pane-placement.test.ts b/ui/src/pages/chat/chat-pane-placement.test.ts new file mode 100644 index 000000000000..eaa2d6c85a97 --- /dev/null +++ b/ui/src/pages/chat/chat-pane-placement.test.ts @@ -0,0 +1,217 @@ +/* @vitest-environment jsdom */ + +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { GatewayBrowserClient } from "../../api/gateway.ts"; +import type { GatewaySessionRow } from "../../api/types.ts"; +import { t } from "../../i18n/index.ts"; +import type { SessionCapability } from "../../lib/sessions/index.ts"; +import { + answerConfirmDialog, + installDialogPolyfill, + waitForConfirmDialogActions, +} from "../../test-helpers/modal-dialog.ts"; +import { resolveChatPanePlacement } from "./chat-pane-placement.ts"; +import { createTestChatPane } from "./chat-pane.test-support.ts"; + +let restoreDialogPolyfill: () => void; + +beforeEach(() => { + restoreDialogPolyfill = installDialogPolyfill(); +}); + +afterEach(() => { + document.body.replaceChildren(); + restoreDialogPolyfill(); + vi.unstubAllGlobals(); +}); + +type ActivePlacement = Extract, { state: "active" }>; + +function activePlacementSession( + key = "agent:main:cloud", +): GatewaySessionRow & { placement: ActivePlacement } { + return { + key, + kind: "direct", + updatedAt: 0, + placement: { + state: "active", + generation: 1, + createdAtMs: 1, + updatedAtMs: 1, + stateChangedAtMs: 1, + environmentId: "worker:one", + activeOwnerEpoch: 1, + workerBundleHash: "a".repeat(64), + workspaceBaseManifestRef: "base-manifest", + remoteWorkspaceDir: "/worker/repo", + }, + }; +} + +describe("chat pane placement", () => { + it("does not reclaim a provisioning placement with a destroyable environment", async () => { + const request = vi.fn(async () => ({ ok: true })); + const { pane } = createTestChatPane({ + client: { request } as unknown as GatewayBrowserClient, + sessions: {} as SessionCapability, + }); + pane.context.gateway.snapshot.hello = { + features: { methods: ["sessions.reclaim"] }, + auth: { role: "operator", scopes: ["operator.admin"] }, + } as never; + + const session = { + key: "agent:main:provisioning", + kind: "direct", + updatedAt: 0, + placement: { + state: "provisioning", + environmentId: "worker:one", + } as GatewaySessionRow["placement"], + } satisfies GatewaySessionRow; + const placement = resolveChatPanePlacement({ + gatewaySnapshot: pane.context.gateway.snapshot, + reclaimingKey: null, + row: session, + }); + const dialogsBefore = document.body.querySelectorAll("openclaw-modal-dialog").length; + await pane.reclaimHeaderPlacement(session); + + expect(placement).toEqual({ + reclaimDisabledReason: "This Gateway does not support this session action.", + }); + expect(document.body.querySelectorAll("openclaw-modal-dialog")).toHaveLength(dialogsBefore); + expect(request).not.toHaveBeenCalled(); + }); + + it("reclaims an active placement after the operator confirms", async () => { + vi.stubGlobal( + "confirm", + vi.fn(() => { + throw new Error("native confirm must not be used"); + }), + ); + const request = vi.fn(async () => ({ ok: true })); + const refreshReplacement = vi.fn(async () => undefined); + const { pane } = createTestChatPane({ + client: { request } as unknown as GatewayBrowserClient, + sessions: { refreshReplacement } as unknown as SessionCapability, + }); + pane.context.gateway.snapshot.hello = { + features: { methods: ["sessions.reclaim"] }, + auth: { role: "operator", scopes: ["operator.admin"] }, + } as never; + const session = activePlacementSession(); + + const reclaim = pane.reclaimHeaderPlacement(session); + const actions = await waitForConfirmDialogActions(); + expect(actions.textContent).toContain("Stop worker"); + answerConfirmDialog(actions, "confirm"); + await reclaim; + + expect(request).toHaveBeenCalledWith( + "sessions.reclaim", + { key: session.key, agentId: "main" }, + { timeoutMs: 10 * 60_000 }, + ); + expect(refreshReplacement).toHaveBeenCalledWith("main"); + }); + + it("does not reclaim when the operator cancels", async () => { + const request = vi.fn(async () => ({ ok: true })); + const { pane } = createTestChatPane({ + client: { request } as unknown as GatewayBrowserClient, + sessions: {} as SessionCapability, + }); + pane.context.gateway.snapshot.hello = { + features: { methods: ["sessions.reclaim"] }, + auth: { role: "operator", scopes: ["operator.admin"] }, + } as never; + const session = activePlacementSession(); + + const reclaim = pane.reclaimHeaderPlacement(session); + const actions = await waitForConfirmDialogActions(); + answerConfirmDialog(actions, "cancel"); + await reclaim; + + expect(request).not.toHaveBeenCalled(); + }); + + it("does not reclaim after the connection changes while confirmation is open", async () => { + const request = vi.fn(async () => ({ ok: true })); + const { pane, state } = createTestChatPane({ + client: { request } as unknown as GatewayBrowserClient, + sessions: {} as SessionCapability, + }); + pane.context.gateway.snapshot.hello = { + features: { methods: ["sessions.reclaim"] }, + auth: { role: "operator", scopes: ["operator.admin"] }, + } as never; + const session = activePlacementSession(); + + const reclaim = pane.reclaimHeaderPlacement(session); + const actions = await waitForConfirmDialogActions(); + pane.connectionGeneration += 1; + answerConfirmDialog(actions, "confirm"); + await reclaim; + + expect(request).not.toHaveBeenCalled(); + expect(state.chatError).toBe(t("sessionsView.actionUnavailable")); + }); + + it("keeps reclaim progress with its session when the pane switches rows", async () => { + let resolveRequest!: (result: { ok: true }) => void; + const request = vi.fn( + () => + new Promise<{ ok: true }>((resolve) => { + resolveRequest = resolve; + }), + ); + const refreshReplacement = vi.fn(async () => undefined); + const { pane, state } = createTestChatPane({ + client: { request } as unknown as GatewayBrowserClient, + sessions: { refreshReplacement } as unknown as SessionCapability, + }); + pane.context.gateway.snapshot.hello = { + features: { methods: ["sessions.reclaim"] }, + auth: { role: "operator", scopes: ["operator.admin"] }, + } as never; + const sessionA = activePlacementSession("agent:main:cloud-a"); + const sessionB = { + ...sessionA, + key: "agent:main:cloud-b", + placement: { + ...sessionA.placement, + environmentId: "worker:two", + remoteWorkspaceDir: "/worker/repo-b", + }, + } satisfies GatewaySessionRow; + + const pendingReclaim = pane.reclaimHeaderPlacement(sessionA); + const actions = await waitForConfirmDialogActions(); + answerConfirmDialog(actions, "confirm"); + await vi.waitFor(() => expect(pane.headerPlacementReclaimingKey).toBe(sessionA.key)); + expect(pane.headerPlacementReclaimingKey).toBe(sessionA.key); + + state.sessionKey = sessionB.key; + expect(state.sessionKey).toBe(sessionB.key); + const placementA = resolveChatPanePlacement({ + gatewaySnapshot: pane.context.gateway.snapshot, + reclaimingKey: pane.headerPlacementReclaimingKey, + row: sessionA, + }); + const placementB = resolveChatPanePlacement({ + gatewaySnapshot: pane.context.gateway.snapshot, + reclaimingKey: pane.headerPlacementReclaimingKey, + row: sessionB, + }); + expect(placementA.reclaimDisabledReason).toBe(t("common.loading")); + expect(placementB.reclaimDisabledReason).toBeUndefined(); + + resolveRequest({ ok: true }); + await pendingReclaim; + + expect(pane.headerPlacementReclaimingKey).toBeNull(); + }); +}); diff --git a/ui/src/pages/chat/chat-pane-placement.ts b/ui/src/pages/chat/chat-pane-placement.ts new file mode 100644 index 000000000000..86ad5707b7fc --- /dev/null +++ b/ui/src/pages/chat/chat-pane-placement.ts @@ -0,0 +1,102 @@ +import type { GatewayBrowserClient } from "../../api/gateway.ts"; +import type { GatewaySessionRow } from "../../api/types.ts"; +import type { ApplicationGatewaySnapshot } from "../../app/context.ts"; +import { + requestCloudWorkerStop, + resolveCloudWorkerStopAction, +} from "../../components/cloud-worker-stop.ts"; +import { t } from "../../i18n/index.ts"; +import { readSessionMethodAccess } from "../../lib/session-method-access.ts"; +import { parseAgentSessionKey } from "../../lib/sessions/session-key.ts"; + +export function resolveChatPanePlacement(params: { + gatewaySnapshot: ApplicationGatewaySnapshot; + reclaimingKey: string | null; + row: GatewaySessionRow | undefined; +}): { reclaimDisabledReason: string | undefined } { + const reclaiming = params.reclaimingKey === params.row?.key; + const action = resolveCloudWorkerStopAction(params.row?.placement); + const access = readSessionMethodAccess(params.gatewaySnapshot, { + method: "sessions.reclaim", + requiredScope: "operator.admin", + }); + const reclaimDisabledReason = reclaiming + ? t("common.loading") + : params.row?.hasActiveRun === true + ? t("sessionsView.activeRun") + : action?.method !== "sessions.reclaim" + ? t("sessionsView.actionUnavailable") + : access.allowed + ? undefined + : access.reason; + return { + reclaimDisabledReason, + }; +} + +export async function reclaimChatPanePlacement(params: { + client: GatewayBrowserClient | null; + connectionGeneration: number; + gatewaySnapshot: ApplicationGatewaySnapshot; + reclaimingKey: string | null; + row: GatewaySessionRow; + isCurrent: (client: GatewayBrowserClient, generation: number) => boolean; + onReclaimingChange: (reclaimingKey: string | null) => void; + publishError: (error: unknown) => void; + refreshReplacement: (agentId?: string | null) => Promise; + requestUpdate: () => void; +}): Promise { + const client = params.client; + const connectionGeneration = params.connectionGeneration; + const action = resolveCloudWorkerStopAction(params.row.placement); + const reclaiming = params.reclaimingKey === params.row.key; + if ( + !client || + reclaiming || + params.row.hasActiveRun === true || + action?.method !== "sessions.reclaim" + ) { + return; + } + const access = readSessionMethodAccess(params.gatewaySnapshot, { + method: "sessions.reclaim", + requiredScope: "operator.admin", + }); + if (!access.allowed) { + params.publishError(access.reason); + return; + } + const { showConfirmDialog } = await import("../../components/confirm-dialog.js"); + const confirmed = await showConfirmDialog({ + message: t("sessionsView.stopCloudWorkerConfirm", { + session: params.row.label || params.row.key, + }), + confirmLabel: t("sessionsView.stopCloudWorkerConfirmAction"), + danger: true, + }); + if (!confirmed) { + return; + } + if (!params.isCurrent(client, connectionGeneration)) { + params.publishError(t("sessionsView.actionUnavailable")); + return; + } + const agentId = parseAgentSessionKey(params.row.key)?.agentId; + params.onReclaimingChange(params.row.key); + try { + await requestCloudWorkerStop(client, action, { + key: params.row.key, + ...(agentId ? { agentId } : {}), + }); + if (params.isCurrent(client, connectionGeneration)) { + await params.refreshReplacement(agentId); + } + } catch (error) { + if (params.isCurrent(client, connectionGeneration)) { + params.publishError(error); + } + } finally { + params.onReclaimingChange(null); + params.requestUpdate(); + } +} diff --git a/ui/src/pages/chat/chat-pane-task-suggestions.ts b/ui/src/pages/chat/chat-pane-task-suggestions.ts index 5bec8c4827a7..78b5b8332279 100644 --- a/ui/src/pages/chat/chat-pane-task-suggestions.ts +++ b/ui/src/pages/chat/chat-pane-task-suggestions.ts @@ -13,7 +13,7 @@ import { taskSuggestionAcceptParams, type TaskSuggestionAcceptMode, } from "../../lib/task-suggestion-acceptance.ts"; -import { discoverCloudProfiles } from "../new-session/cloud-profile-discovery.ts"; +import { discoverPlaceCatalog } from "../new-session/cloud-profile-discovery.ts"; import { ChatPaneSharing } from "./chat-pane-sharing.ts"; import { resolveChatAgentId } from "./chat-state-route.ts"; @@ -49,7 +49,7 @@ export abstract class ChatPaneTaskSuggestions extends ChatPaneSharing { return; } try { - const profiles = await discoverCloudProfiles(scope.client, true); + const { profiles } = await discoverPlaceCatalog(scope.client, true); if (!this.isConnectionScopeCurrent(scope)) { return; } diff --git a/ui/src/pages/chat/chat-pane.test-support.ts b/ui/src/pages/chat/chat-pane.test-support.ts index 4023b39d22c7..1560afe11047 100644 --- a/ui/src/pages/chat/chat-pane.test-support.ts +++ b/ui/src/pages/chat/chat-pane.test-support.ts @@ -120,6 +120,8 @@ export type TestChatPane = HTMLElement & { agentWorkspace: string | undefined, workspaceGit: boolean, ) => Promise; + headerPlacementReclaimingKey: string | null; + reclaimHeaderPlacement: (row: GatewaySessionRow) => Promise; markSessionRead: (row: GatewaySessionRow | undefined) => void; renderPaneHeader: ( workspace: ReturnType, diff --git a/ui/src/pages/chat/components/chat-pane-header.test.ts b/ui/src/pages/chat/components/chat-pane-header.test.ts index 828e4b7c33fb..c100c12bbf0d 100644 --- a/ui/src/pages/chat/components/chat-pane-header.test.ts +++ b/ui/src/pages/chat/components/chat-pane-header.test.ts @@ -302,6 +302,56 @@ describe("chat pane header", () => { expect(props.onBeginRename).toHaveBeenCalledOnce(); }); + it("renders a quiet cloud placement chip with the canonical stop action", () => { + const onPlacementReclaim = vi.fn(); + const { container } = mount({ + session: row({ + placement: { + state: "active", + generation: 1, + createdAtMs: 100_000, + updatedAtMs: 300_000, + stateChangedAtMs: 300_000, + environmentId: "worker:one", + activeOwnerEpoch: 1, + workerBundleHash: "a".repeat(64), + workspaceBaseManifestRef: "base-manifest", + remoteWorkspaceDir: "/worker/repo", + }, + }), + onPlacementReclaim, + }); + + expect(container.querySelector(".chat-pane__placement-chip")?.textContent?.trim()).toBe( + "Runs on Cloud", + ); + expect(container.querySelector(".chat-pane__placement-state")).toBeNull(); + expect(container.querySelector(".chat-pane__placement-note")).toBeNull(); + const actions = container.querySelectorAll(".chat-pane__placement-menu wa-dropdown-item"); + expect(actions).toHaveLength(1); + expect(actions[0]?.textContent?.trim()).toBe("Stop cloud worker…"); + expect(actions[0]?.classList.contains("session-menu__item--destructive")).toBe(true); + expect(actions[0]?.getAttribute("variant")).toBe("danger"); + expect(actions[0]?.querySelector(".session-menu__icon")).not.toBeNull(); + actions[0]?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + expect(onPlacementReclaim).toHaveBeenCalledOnce(); + }); + + it.each(["local", "reclaimed"] as const)("hides the placement chip for %s state", (state) => { + const { container } = mount({ + session: row({ + placement: { + state, + generation: 1, + createdAtMs: 1, + updatedAtMs: 1, + stateChangedAtMs: 1, + }, + }), + }); + expect(container.querySelector(".chat-pane__placement-chip")).toBeNull(); + }); + it("places pane presence between the identity trail and face control", () => { const { container } = mount({ presence: html``, @@ -456,7 +506,7 @@ describe("chat pane header", () => { }), canReveal: false, }); - expect(container.querySelector(".chat-pane__cloud")).not.toBeNull(); + expect(container.querySelector(".chat-pane__placement-chip")).not.toBeNull(); expect(container.querySelector('wa-dropdown-item[value="reveal"]')).toBeNull(); expect(container.querySelector('wa-dropdown-item[value="copy-path"]')).not.toBeNull(); }); diff --git a/ui/src/pages/chat/components/chat-pane-header.ts b/ui/src/pages/chat/components/chat-pane-header.ts index dd5cffadaa25..4a383d4267a1 100644 --- a/ui/src/pages/chat/components/chat-pane-header.ts +++ b/ui/src/pages/chat/components/chat-pane-header.ts @@ -27,6 +27,7 @@ import { areUiSessionKeysEquivalent, resolveUiSessionNavigationParentKey, } from "../../../lib/sessions/session-key.ts"; +import { renderChatPanePlacement } from "./chat-pane-placement.ts"; export type ChatPaneHeaderAction = "reveal" | "copy-path" | "copy-branch"; @@ -68,6 +69,7 @@ type ChatPaneHeaderProps = { faceControl?: TemplateResult | typeof nothing; sharingControl?: TemplateResult | typeof nothing; sessionMenuAction: TemplateResult | typeof nothing; + placementReclaimDisabledReason?: string; nativeGateways?: NativeGatewaysCapability | null; gatewaysSnapshot?: NativeGatewaysSnapshot | null; onboarding?: boolean; @@ -78,6 +80,7 @@ type ChatPaneHeaderProps = { onMenuOpenChange: (open: boolean) => void; onMenuAction: (action: ChatPaneHeaderAction) => void; onOpenParentSession: (sessionKey: string) => void; + onPlacementReclaim?: () => void; onBranchSelect: (leafEntryId: string) => void; onOpenSplitView?: () => void; onSplitDown?: (paneId: string) => void; @@ -396,9 +399,6 @@ function renderGatewayPicker(props: ChatPaneHeaderProps) { } export function renderChatPaneHeader(props: ChatPaneHeaderProps) { - const placementState = props.session?.placement?.state; - const cloud = isCloudWorkerPlacementState(placementState); - const cloudLabel = cloud ? t("sessionsView.cloudWorkerPlacement", { state: placementState }) : ""; const copyPathLabel = props.copiedAction === "copy-path" ? t("chat.sessionHeader.copied") @@ -432,15 +432,6 @@ export function renderChatPaneHeader(props: ChatPaneHeaderProps) { ` : nothing} - ${cloud - ? html`${icons.globe}` - : nothing} ${props.session?.incognito ? html` 1 ? html` diff --git a/ui/src/pages/chat/components/chat-pane-placement.ts b/ui/src/pages/chat/components/chat-pane-placement.ts new file mode 100644 index 000000000000..e239bb767035 --- /dev/null +++ b/ui/src/pages/chat/components/chat-pane-placement.ts @@ -0,0 +1,42 @@ +import { html, nothing, type TemplateResult } from "lit"; +import type { GatewaySessionRow } from "../../../api/types.ts"; +import { icons } from "../../../components/icons.ts"; +import { isCloudWorkerPlacementState } from "../../../components/session-row-badges.ts"; +import { t } from "../../../i18n/index.ts"; +import { formatRelativeTimestamp } from "../../../lib/format.ts"; + +export function renderChatPanePlacement(props: { + session: GatewaySessionRow | undefined; + placementReclaimDisabledReason?: string; + onPlacementReclaim?: () => void; +}): TemplateResult | typeof nothing { + const placementState = props.session?.placement?.state; + if (!isCloudWorkerPlacementState(placementState)) { + return nothing; + } + const label = t("newSession.runsOn", { place: t("newSession.cloud") }); + const disabledReason = props.placementReclaimDisabledReason; + const age = formatRelativeTimestamp(props.session?.placement?.stateChangedAtMs, { + fallback: "", + }); + const exceptionState = + placementState === "active" ? nothing : `${placementState}${age ? ` · ${age}` : ""}`; + return html` + + + ${exceptionState === nothing + ? nothing + : html`
${exceptionState}
`} + !disabledReason && props.onPlacementReclaim?.()} + > + + ${t("sessionsView.stopCloudWorker")} + + + `; +} diff --git a/ui/src/pages/new-session/cloud-profile-discovery.ts b/ui/src/pages/new-session/cloud-profile-discovery.ts index db35175ee901..f128a1a8d78f 100644 --- a/ui/src/pages/new-session/cloud-profile-discovery.ts +++ b/ui/src/pages/new-session/cloud-profile-discovery.ts @@ -1,6 +1,6 @@ import type { GatewayBrowserClient } from "../../api/gateway.ts"; -import { requestCloudProfiles } from "./cloud-target.ts"; -import type { DraftCloudProfile } from "./discovery.ts"; +import { requestPlaceCatalog } from "./cloud-target.ts"; +import type { DraftCloudProfile, DraftEnvironment } from "./discovery.ts"; export const CLOUD_PROFILE_RETRY_DELAYS_MS = [1_000, 3_000, 10_000, 30_000, 60_000] as const; @@ -13,9 +13,9 @@ export function selectProfiles( return { profiles: unsupported ? [] : profiles, unsupported }; } -export function discoverCloudProfiles( +export function discoverPlaceCatalog( client: Pick, admin: boolean, -): Promise { - return admin ? requestCloudProfiles(client) : Promise.resolve([]); +): Promise<{ profiles: DraftCloudProfile[]; environments: DraftEnvironment[] }> { + return admin ? requestPlaceCatalog(client) : Promise.resolve({ profiles: [], environments: [] }); } diff --git a/ui/src/pages/new-session/cloud-target.ts b/ui/src/pages/new-session/cloud-target.ts index f00f32261541..94444fd83745 100644 --- a/ui/src/pages/new-session/cloud-target.ts +++ b/ui/src/pages/new-session/cloud-target.ts @@ -3,14 +3,17 @@ import type { EnvironmentsListResult } from "../../../../packages/gateway-protoc import type { GatewayBrowserClient } from "../../api/gateway.ts"; import { icons } from "../../components/icons.ts"; import { t } from "../../i18n/index.ts"; -import type { DraftCloudProfile } from "./discovery.ts"; -import { readDraftCloudProfiles } from "./discovery.ts"; +import type { DraftCloudProfile, DraftEnvironment } from "./discovery.ts"; +import { readDraftCloudProfiles, readDraftEnvironments } from "./discovery.ts"; -export async function requestCloudProfiles( +export async function requestPlaceCatalog( client: Pick, -): Promise { +): Promise<{ profiles: DraftCloudProfile[]; environments: DraftEnvironment[] }> { const result = await client.request("environments.list", {}); - return readDraftCloudProfiles(result?.profiles); + return { + profiles: readDraftCloudProfiles(result?.profiles), + environments: readDraftEnvironments(result?.environments), + }; } type SessionMenuItemOptions = { diff --git a/ui/src/pages/new-session/discovery.test.ts b/ui/src/pages/new-session/discovery.test.ts index 453f775c6fcc..91a642c43a1e 100644 --- a/ui/src/pages/new-session/discovery.test.ts +++ b/ui/src/pages/new-session/discovery.test.ts @@ -1,6 +1,6 @@ // @vitest-environment node import { describe, expect, it } from "vitest"; -import { readDraftCloudProfiles, readDraftNodes } from "./discovery.ts"; +import { readDraftCloudProfiles, readDraftEnvironments, readDraftNodes } from "./discovery.ts"; describe("readDraftNodes", () => { it("ignores non-record array entries without throwing", () => { @@ -29,21 +29,45 @@ describe("readDraftNodes", () => { ]); }); }); - describe("readDraftCloudProfiles", () => { it("keeps closed profile summaries in stable order", () => { expect( readDraftCloudProfiles([ null, 42, - { id: " zeta ", providerId: " static-ssh ", settings: { token: "hidden" } }, + { + id: " zeta ", + providerId: " static-ssh ", + settings: { token: "hidden" }, + }, { id: "aws", providerId: "crabbox" }, + { id: "legacy", providerId: "static-ssh" }, { id: "", providerId: "crabbox" }, { id: "missing-provider" }, ]), ).toEqual([ { id: "aws", providerId: "crabbox" }, + { id: "legacy", providerId: "static-ssh" }, { id: "zeta", providerId: "static-ssh" }, ]); }); }); + +describe("readDraftEnvironments", () => { + it("keeps the closed environment types while rejecting malformed entries", () => { + expect( + readDraftEnvironments([ + { id: "gateway", type: "local", label: "Gateway" }, + { id: "node:macbook", type: "node" }, + { id: "worker:aws", type: "worker" }, + { id: "future", type: "future" }, + { id: "", type: "node" }, + { id: "missing-type" }, + ]), + ).toEqual([ + { id: "gateway", type: "local" }, + { id: "node:macbook", type: "node" }, + { id: "worker:aws", type: "worker" }, + ]); + }); +}); diff --git a/ui/src/pages/new-session/discovery.ts b/ui/src/pages/new-session/discovery.ts index d8ff8f454286..153a74549d3b 100644 --- a/ui/src/pages/new-session/discovery.ts +++ b/ui/src/pages/new-session/discovery.ts @@ -32,6 +32,11 @@ export type DraftCloudProfile = { providerId: string; }; +export type DraftEnvironment = { + id: string; + type: "local" | "node" | "worker"; +}; + export type BrowserTarget = { nodeId: string; label: string }; export function readDraftNodes(value: unknown): DraftNode[] { @@ -83,14 +88,40 @@ export function readDraftNodes(value: unknown): DraftNode[] { export function readDraftCloudProfiles(value: unknown): DraftCloudProfile[] { return (Array.isArray(value) ? value : []) - .flatMap((raw) => { + .flatMap((raw) => { if (!raw || typeof raw !== "object") { return []; } - const profile = raw as { id?: unknown; providerId?: unknown }; + const profile = raw as { + id?: unknown; + providerId?: unknown; + }; const id = normalizeOptionalString(profile.id); const providerId = normalizeOptionalString(profile.providerId); - return id && providerId ? [{ id, providerId }] : []; + if (!id || !providerId) { + return []; + } + return [{ id, providerId }]; + }) + .toSorted((left, right) => left.id.localeCompare(right.id)); +} + +export function readDraftEnvironments(value: unknown): DraftEnvironment[] { + return (Array.isArray(value) ? value : []) + .flatMap((raw) => { + if (!raw || typeof raw !== "object") { + return []; + } + const environment = raw as { + id?: unknown; + type?: unknown; + }; + const id = normalizeOptionalString(environment.id); + const type = normalizeOptionalString(environment.type); + if (!id || (type !== "local" && type !== "node" && type !== "worker")) { + return []; + } + return [{ id, type }]; }) .toSorted((left, right) => left.id.localeCompare(right.id)); } diff --git a/ui/src/pages/new-session/draft-gateway-state.ts b/ui/src/pages/new-session/draft-gateway-state.ts index e4fcd67afbfc..f10b124d9e51 100644 --- a/ui/src/pages/new-session/draft-gateway-state.ts +++ b/ui/src/pages/new-session/draft-gateway-state.ts @@ -11,7 +11,7 @@ import { normalizeAgentId } from "../../lib/sessions/session-key.ts"; import * as catalog from "./catalog-target.ts"; import { CLOUD_PROFILE_RETRY_DELAYS_MS, - discoverCloudProfiles, + discoverPlaceCatalog, selectProfiles, } from "./cloud-profile-discovery.ts"; import { @@ -19,7 +19,7 @@ import { resolveSubmissionOutcomeReason, type SubmissionOutcomeReason, } from "./cloud-recovery-state.ts"; -import type { DraftCloudProfile } from "./discovery.ts"; +import type { DraftCloudProfile, DraftEnvironment } from "./discovery.ts"; import { discoverGatewayName } from "./gateway-name-discovery.ts"; import type { NewSessionRouteData } from "./location.ts"; import { @@ -66,6 +66,7 @@ type DraftGatewayCallbacks = { export class DraftGatewayState { private gatewayNameValue = ""; private cloudProfilesValue: DraftCloudProfile[] = []; + private environmentsValue: DraftEnvironment[] | null = null; private cloudProfilesReadyValue = false; private catalogRetryingValue = false; private gatewaySource: ApplicationContext["gateway"] | null = null; @@ -87,7 +88,10 @@ export class DraftGatewayState { private preferenceWrite: Promise = Promise.resolve(); private readonly gatewayNameTask: Task; - private readonly cloudProfileTask: Task; + private readonly cloudProfileTask: Task< + readonly unknown[], + { profiles: DraftCloudProfile[]; environments: DraftEnvironment[] } + >; constructor( host: ReactiveControllerHost, @@ -118,14 +122,16 @@ export class DraftGatewayState { this.gatewayRecoveryScopeValue, ] as const, task: ([client, _connectionEpoch, admin]) => - client ? discoverCloudProfiles(client, admin) : initialState, - onComplete: (profiles) => { + client ? discoverPlaceCatalog(client, admin) : initialState, + onComplete: (placeCatalog) => { this.resetCloudProfileRetry(); - this.applyCloudProfiles(profiles); + this.environmentsValue = placeCatalog.environments; + this.applyCloudProfiles(placeCatalog.profiles); this.cloudProfilesReadyValue = true; this.callbacks.requestUpdate(); }, onError: () => { + // Keep the last environment catalog across a transient client refresh on this Gateway. this.cloudProfilesValue = []; this.cloudProfilesReadyValue = false; this.scheduleCloudProfileRetry(); @@ -142,6 +148,10 @@ export class DraftGatewayState { return this.cloudProfilesValue; } + get environments(): readonly DraftEnvironment[] | null { + return this.environmentsValue; + } + get cloudProfilesReady(): boolean { return this.cloudProfilesReadyValue; } @@ -183,8 +193,9 @@ export class DraftGatewayState { const connected = snapshot.phase === "connected"; const firstBind = this.gatewaySource === null; const gatewayUrlChanged = !firstBind && this.gatewayUrlValue !== gateway.connection.gatewayUrl; + const gatewaySourceChanged = !firstBind && this.gatewaySource !== gateway; const identityChanged = - !firstBind && (this.gatewaySource !== gateway || this.gatewayClientValue !== snapshot.client); + !firstBind && (gatewaySourceChanged || this.gatewayClientValue !== snapshot.client); const connectionChanged = !firstBind && this.gatewayConnectedValue !== connected; const becameConnected = connected && (identityChanged || !this.gatewayConnectedValue); const recoveryScopeBecameReady = @@ -204,9 +215,10 @@ export class DraftGatewayState { this.callbacks.onVisibilityRetired(); } if (gatewayUrlChanged || identityChanged || connectionChanged || recoveryScope.changed) { + const ownerChanged = gatewaySourceChanged || gatewayUrlChanged || recoveryScope.changed; const gatewayIdentityChanged = gatewayUrlChanged || recoveryScope.changed; this.invalidateDiscovery( - gatewayIdentityChanged, + ownerChanged, resolveSubmissionOutcomeReason({ gatewayIdentityChanged, cloudDraftOwned: Boolean(this.read().pendingCloud.sessionKey), @@ -244,6 +256,9 @@ export class DraftGatewayState { this.gatewayNameValue = ""; this.cloudProfilesValue = []; this.cloudProfilesReadyValue = false; + if (resetHostSelection) { + this.environmentsValue = null; + } this.resetCloudProfileRetry(); this.callbacks.onInvalidate(resetHostSelection, submissionOutcome); this.callbacks.requestUpdate(); diff --git a/ui/src/pages/new-session/new-session-page.ts b/ui/src/pages/new-session/new-session-page.ts index 5c73aa02e6f4..7cd4848659f8 100644 --- a/ui/src/pages/new-session/new-session-page.ts +++ b/ui/src/pages/new-session/new-session-page.ts @@ -370,6 +370,7 @@ class NewSessionPage extends OpenClawLightDomElement { projectCloneError: this.browser.projectCloneError, projectId: this.place.projectId, execNodes: this.place.isAdmin() ? execNodes : [], + environments: this.place.isAdmin() ? this.gateway.environments : [], gatewayName: this.gateway.gatewayName, cloudProfiles: this.place.isAdmin() ? cloudProfiles : [], cloudProfileId: this.place.cloudProfileId, diff --git a/ui/src/pages/new-session/place-picker-sections.ts b/ui/src/pages/new-session/place-picker-sections.ts new file mode 100644 index 000000000000..2059e8bac790 --- /dev/null +++ b/ui/src/pages/new-session/place-picker-sections.ts @@ -0,0 +1,25 @@ +import type { DraftCloudProfile, DraftEnvironment, DraftNode } from "./discovery.ts"; + +export function resolvePlacePickerSections(params: { + environments: readonly DraftEnvironment[] | null; + execNodes: readonly DraftNode[]; + cloudProfiles: readonly DraftCloudProfile[]; +}): { deviceNodes: DraftNode[]; cloudProfiles: DraftCloudProfile[] } { + const environmentById = params.environments + ? new Map(params.environments.map((environment) => [environment.id, environment])) + : null; + return { + deviceNodes: params.execNodes.filter((node) => { + if (!node.connected || !node.canExec) { + return false; + } + if (environmentById === null || environmentById.size === 0) { + // Missing and empty catalogs preserve the established live-node fallback. + return true; + } + const environment = environmentById.get(`node:${node.nodeId}`); + return environment?.type === "node"; + }), + cloudProfiles: [...params.cloudProfiles], + }; +} diff --git a/ui/src/pages/new-session/place-picker.test.ts b/ui/src/pages/new-session/place-picker.test.ts index f5f88d5b1ca9..c09f2546fd12 100644 --- a/ui/src/pages/new-session/place-picker.test.ts +++ b/ui/src/pages/new-session/place-picker.test.ts @@ -1,5 +1,7 @@ import { render } from "lit"; import { describe, expect, it, vi } from "vitest"; +import { readDraftEnvironments } from "./discovery.ts"; +import { resolvePlacePickerSections } from "./place-picker-sections.ts"; import { projectCloneInput, renderPlaceSelect } from "./place-picker.ts"; type PlaceSelectParams = Parameters[0]; @@ -24,6 +26,7 @@ function placeParams(overrides: Partial = {}): PlaceSelectPar projectCloneError: null, projectId: "", execNodes: [], + environments: null, gatewayName: "", cloudProfiles: [], cloudProfileId: "", @@ -160,3 +163,117 @@ describe("project picker", () => { expect(onCloneProject).toHaveBeenCalledWith(gitUrl); }); }); + +describe("Where picker", () => { + it("uses node presence until a non-empty authoritative environment catalog arrives", () => { + const execNodes = [ + { + nodeId: "usable", + displayName: "Usable", + connected: true, + canExec: true, + canBrowse: false, + }, + { + nodeId: "disconnected", + displayName: "Disconnected", + connected: false, + canExec: true, + canBrowse: false, + }, + { + nodeId: "no-exec", + displayName: "No exec", + connected: true, + canExec: false, + canBrowse: false, + }, + ]; + + expect( + resolvePlacePickerSections({ environments: null, execNodes, cloudProfiles: [] }).deviceNodes, + ).toEqual([execNodes[0]]); + expect( + resolvePlacePickerSections({ environments: [], execNodes, cloudProfiles: [] }).deviceNodes, + ).toEqual([execNodes[0]]); + }); + + it("groups usable places from environment types and the legacy node catalog", () => { + const container = document.createElement("div"); + const connectedExecNodes = [ + "macbook", + "worker", + "local", + "missing-environment", + "future-type", + ].map((nodeId) => ({ + nodeId, + displayName: nodeId, + connected: true, + canExec: true, + canBrowse: false, + })); + render( + renderPlaceSelect( + placeParams({ + folder: "", + execNodes: [ + ...connectedExecNodes, + { + nodeId: "offline", + displayName: "Offline Mac", + connected: false, + canExec: false, + canBrowse: false, + }, + { + nodeId: "no-exec", + displayName: "No exec", + connected: true, + canExec: false, + canBrowse: false, + }, + ], + environments: readDraftEnvironments([ + { id: "gateway", type: "local" }, + { id: "node:macbook", type: "node" }, + { id: "node:worker", type: "worker" }, + { id: "node:local", type: "local" }, + { id: "node:offline", type: "node" }, + { id: "node:no-exec", type: "node" }, + { id: "node:future-type", type: "future" }, + ]), + gatewayName: "Studio", + cloudProfiles: [ + { id: "aws", providerId: "crabbox" }, + { id: "legacy", providerId: "static-ssh" }, + ], + worktreeAvailable: true, + showDestinations: true, + }), + ), + container, + ); + + const titles = [...container.querySelectorAll(".new-session-page__menu-title")].map((element) => + element.textContent?.trim(), + ); + expect(titles).toEqual(["Folder", "Projects", "Places", "This gateway", "Devices", "Cloud"]); + expect(container.querySelector('[data-value="node:macbook"]')).not.toBeNull(); + for (const nodeId of [ + "worker", + "local", + "missing-environment", + "future-type", + "offline", + "no-exec", + ]) { + expect(container.querySelector(`[data-value="node:${nodeId}"]`)).toBeNull(); + } + expect(container.querySelector('[data-value="cloud:aws"]')).not.toBeNull(); + expect(container.querySelector('[data-value="cloud:legacy"]')).not.toBeNull(); + + const gateway = container.querySelector('[data-value="gateway"]'); + expect(gateway?.lastElementChild?.classList.contains("session-menu__check")).toBe(true); + }); +}); diff --git a/ui/src/pages/new-session/place-picker.ts b/ui/src/pages/new-session/place-picker.ts index 7afe7c47cc5c..488048ec65b4 100644 --- a/ui/src/pages/new-session/place-picker.ts +++ b/ui/src/pages/new-session/place-picker.ts @@ -8,9 +8,16 @@ import type { import { icons } from "../../components/icons.ts"; import { t } from "../../i18n/index.ts"; import { renderCloudProfileMenuItems, renderSessionMenuItem } from "./cloud-target.ts"; -import type { BrowserTarget, DraftBranches, DraftCloudProfile, DraftNode } from "./discovery.ts"; +import type { + BrowserTarget, + DraftBranches, + DraftCloudProfile, + DraftEnvironment, + DraftNode, +} from "./discovery.ts"; import { folderDisplayName } from "./path.ts"; import { disambiguate, isPhoneFamily, nodeTooltip } from "./place-labels.ts"; +import { resolvePlacePickerSections } from "./place-picker-sections.ts"; function parentFolderDisplayName(path: string): string | undefined { const trimmed = path.replace(/[\\/]+$/u, ""); @@ -177,6 +184,7 @@ export function renderPlaceSelect(params: { projectCloneError: string | null; projectId: string; execNodes: DraftNode[]; + environments: readonly DraftEnvironment[] | null; gatewayName: string; cloudProfiles: readonly DraftCloudProfile[]; cloudProfileId: string; @@ -248,6 +256,7 @@ export function renderPlaceSelect(params: { const activeProfile = params.cloudProfiles.find( (profile) => profile.id === params.cloudProfileId, ); + const { deviceNodes, cloudProfiles } = resolvePlacePickerSections(params); const gatewayLabel = params.gatewayName ? t("newSession.gatewayNamed", { name: params.gatewayName }) : t("newSession.gateway"); @@ -258,10 +267,16 @@ export function renderPlaceSelect(params: { : gatewayLabel; const label = params.showDestinations ? `${folderLabel} · ${destinationLabel}` : folderLabel; const effectiveFolder = folder || params.workspace; - const recentItems = params.recents.map((recent) => { + const recents = params.recents.filter( + (recent) => + recent.kind !== "folder" || + !recent.execNode || + deviceNodes.some((node) => node.nodeId === recent.execNode), + ); + const recentItems = recents.map((recent) => { const node = recent.kind === "folder" && recent.execNode - ? params.execNodes.find((candidate) => candidate.nodeId === recent.execNode) + ? deviceNodes.find((candidate) => candidate.nodeId === recent.execNode) : undefined; const recentLabel = params.showDestinations && node @@ -279,7 +294,7 @@ export function renderPlaceSelect(params: { ? `${recent.folder}${recent.execNode ? ` · ${recent.execNode.slice(0, 8)}` : ""}` : recent.projectId, ]); - const nodeSuffixes = disambiguate(params.execNodes, (node) => node.displayName, [ + const nodeSuffixes = disambiguate(deviceNodes, (node) => node.displayName, [ (node) => node.modelIdentifier, (node) => node.remoteIp, (node) => node.nodeId.slice(0, 8), @@ -469,7 +484,7 @@ export function renderPlaceSelect(params: { ${t("newSession.projectsAdminHint")}
` : nothing} - ${params.recents.length > 0 + ${recents.length > 0 ? html`
${t("newSession.recentFolders")}
${recentItems.map((recent, index) => { @@ -519,6 +534,7 @@ export function renderPlaceSelect(params: { ${params.showDestinations ? html`
${t("newSession.places")}
+
${t("newSession.thisGateway")}
${renderSessionMenuItem( { value: "gateway", @@ -529,24 +545,34 @@ export function renderPlaceSelect(params: { }, params.submitting, )} - ${params.execNodes.map((node, index) => - renderSessionMenuItem( - { - value: `node:${node.nodeId}`, - label: node.displayName, - icon: isPhoneFamily(node.deviceFamily) - ? icons.monitorSmartphone - : icons.monitor, - sub: nodeSuffixes[index], - checked: params.execNode === node.nodeId, - title: nodeTooltip(node), - onSelect: () => params.onSelectExecNode(node.nodeId), - }, - params.submitting, - ), - )} + ${deviceNodes.length > 0 + ? html` +
${t("tabs.devices")}
+ ${deviceNodes.map((node, index) => + renderSessionMenuItem( + { + value: `node:${node.nodeId}`, + label: node.displayName, + icon: isPhoneFamily(node.deviceFamily) + ? icons.monitorSmartphone + : icons.monitor, + sub: nodeSuffixes[index], + checked: params.execNode === node.nodeId, + title: nodeTooltip(node), + onSelect: () => params.onSelectExecNode(node.nodeId), + }, + params.submitting, + ), + )} + ` + : nothing} + ${cloudProfiles.length > 0 || (params.cloudProfileId && !activeProfile) + ? html`
+ ${t("newSession.cloud")} +
` + : nothing} ${renderCloudProfileMenuItems({ - profiles: params.cloudProfiles, + profiles: cloudProfiles, selectedId: params.cloudProfileId, submitting: params.submitting, icon: icons.server, diff --git a/ui/src/pages/new-session/recent-places.test.ts b/ui/src/pages/new-session/recent-places.test.ts index b66ddd247b6c..cdcbf0cd3e2d 100644 --- a/ui/src/pages/new-session/recent-places.test.ts +++ b/ui/src/pages/new-session/recent-places.test.ts @@ -4,16 +4,17 @@ import { isKnownWorkspacePath } from "./path.ts"; import { recentPlaces } from "./recent-places.ts"; describe("recentPlaces", () => { - it("deduplicates, caps, skips the workspace and unknown nodes, and prefers exec cwd", () => { + it("deduplicates locations, caps newest-first, and keeps matching basenames on distinct runners", () => { expect( recentPlaces( [ { execCwd: "/workspace" }, { execCwd: "/node/repo", execNode: "macbook" }, { execCwd: "/node/repo", execNode: "macbook" }, + { execCwd: "/gateway/repo" }, { execCwd: "/gone/repo", execNode: "retired" }, { - execCwd: "/preferred/repo", + execCwd: "/preferred/selected", worktree: { repoRoot: "/ignored/worktree" }, }, { worktree: { repoRoot: "/worktree/one" } }, @@ -28,9 +29,9 @@ describe("recentPlaces", () => { ), ).toEqual([ { folder: "/node/repo", execNode: "macbook" }, - { folder: "/preferred/repo", execNode: "" }, + { folder: "/gateway/repo", execNode: "" }, + { folder: "/preferred/selected", execNode: "" }, { folder: "/worktree/one", execNode: "" }, - { folder: "/cwd/two", execNode: "" }, ]); }); diff --git a/ui/src/styles/chat/split-view.css b/ui/src/styles/chat/split-view.css index ea702915aa6a..b5b873551ee4 100644 --- a/ui/src/styles/chat/split-view.css +++ b/ui/src/styles/chat/split-view.css @@ -286,7 +286,6 @@ openclaw-chat-pane { } } -.chat-pane__cloud, .chat-pane__incognito { display: inline-flex; flex: 0 0 auto; @@ -294,7 +293,6 @@ openclaw-chat-pane { color: var(--muted); } -.chat-pane__cloud svg, .chat-pane__incognito svg, .chat-pane__workspace-chip svg { width: 14px; @@ -328,6 +326,42 @@ openclaw-chat-pane { min-width: 0; } +.chat-pane__placement-menu { + flex: 0 0 auto; +} + +.chat-pane__placement-menu::part(menu) { + width: 250px; + padding: 6px; + border: 1px solid color-mix(in srgb, var(--border-strong) 78%, transparent); + border-radius: 8px; + background: var(--bg-elevated); + box-shadow: var(--shadow-lg); +} + +.chat-pane__placement-chip { + padding: 2px; + border: 0; + background: transparent; + color: var(--muted); + font: inherit; + font-size: 11px; + cursor: var(--cursor-action); +} + +.chat-pane__placement-chip:hover, +.chat-pane__placement-chip:focus-visible { + color: var(--text); + outline: none; +} + +.chat-pane__placement-state { + padding: 6px 8px; + color: var(--muted); + font-size: 11px; + font-weight: 600; +} + .chat-pane__gateway-menu { flex: 0 1 auto; min-width: 0; From 1da8fffbcb1bba73172f0898a7b420e217ae5f79 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:23:34 -0700 Subject: [PATCH 057/165] improve: speed up secrets audit test shard (#122504) * test: speed up secrets audit coverage * test: complete daemon plugin fixtures --------- Co-authored-by: Amp --- src/commands/daemon-install-helpers.test.ts | 2 + src/secrets/audit.test.ts | 280 ++++++------------ src/secrets/audit.ts | 13 +- src/secrets/channel-contract-api.ts | 3 +- ...get-registry-data.current-snapshot.test.ts | 111 ++++++- src/secrets/target-registry-data.ts | 25 +- src/secrets/target-registry-query.ts | 74 +++-- src/secrets/target-registry.fast-path.test.ts | 86 +++++- src/secrets/target-registry.test.ts | 16 + 9 files changed, 385 insertions(+), 225 deletions(-) diff --git a/src/commands/daemon-install-helpers.test.ts b/src/commands/daemon-install-helpers.test.ts index ebd079ead2ea..4cb157bf25c6 100644 --- a/src/commands/daemon-install-helpers.test.ts +++ b/src/commands/daemon-install-helpers.test.ts @@ -235,6 +235,7 @@ async function buildPluginConfigExecSecretRefPlan(home: string) { id: "acme-secrets", origin: "global", rootDir: pluginRoot, + channels: [], secretProviderIntegrations: { "secret-store": { source: "exec", @@ -252,6 +253,7 @@ async function buildPluginConfigExecSecretRefPlan(home: string) { { id: "acme-plugin", origin: "global", + channels: [], configContracts: { secretInputs: { paths: [{ path: "apiKey", expected: "string" }], diff --git a/src/secrets/audit.test.ts b/src/secrets/audit.test.ts index d6a4409d937a..f0deb68263ff 100644 --- a/src/secrets/audit.test.ts +++ b/src/secrets/audit.test.ts @@ -2,7 +2,7 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; -import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js"; import { resolveAuthProfileDatabasePath, @@ -72,6 +72,7 @@ async function writeExecSecretsAuditConfig(params: { baseUrl: string; modelId: string; modelName: string; + headerRefId?: string; }>; }) { await writeJsonFile(params.fixture.configPath, { @@ -98,6 +99,17 @@ async function writeExecSecretsAuditConfig(params: { provider: "execmain", id: `providers/${provider.id}/apiKey`, }, + ...(provider.headerRefId + ? { + headers: { + Authorization: { + source: "exec", + provider: "execmain", + id: provider.headerRefId, + }, + }, + } + : {}), models: [{ id: provider.modelId, name: provider.modelName }], }, ]), @@ -216,18 +228,6 @@ async function seedAuditFixture(fixture: AuditFixture): Promise { describe("secrets audit", () => { let fixture: AuditFixture; - beforeAll(async () => { - const warmFixture = await createAuditFixture(); - try { - await writeJsonFile(warmFixture.configPath, {}); - await runSecretsAudit({ env: warmFixture.env }); - } finally { - closeOpenClawAgentDatabasesForTest(); - closeOpenClawStateDatabaseForTest(); - await fs.rm(warmFixture.rootDir, { recursive: true, force: true }); - } - }); - async function writeModelsProvider( overrides: Partial<{ apiKey: unknown; @@ -413,7 +413,7 @@ describe("secrets audit", () => { logPath: execLogPath, values: { "providers/openai/apiKey": "value:providers/openai/apiKey", - "providers/moonshot/apiKey": "value:providers/moonshot/apiKey", + "providers/openai/headers/Authorization": "value:providers/openai/headers/Authorization", }, }); await writeExecSecretsAuditConfig({ @@ -425,18 +425,14 @@ describe("secrets audit", () => { baseUrl: "https://api.openai.com/v1", modelId: "gpt-5", modelName: "gpt-5", - }, - { - id: "moonshot", - baseUrl: "https://api.moonshot.cn/v1", - modelId: "moonshot-v1-8k", - modelName: "moonshot-v1-8k", + headerRefId: "providers/openai/headers/Authorization", }, ], }); const report = await runSecretsAudit({ env: fixture.env, allowExec: true }); expect(report.summary.unresolvedRefCount).toBe(0); + expect(report.resolution.refsChecked).toBe(2); const callLog = await fs.readFile(execLogPath, "utf8"); const callCount = countNonEmptyLines(callLog); @@ -480,14 +476,15 @@ describe("secrets audit", () => { baseUrl: "https://api.openai.com/v1", api: "openai-completions", apiKey: { source: "exec", provider: "execmain", id: "providers/openai/apiKey" }, + headers: { + Authorization: { + source: "exec", + provider: "execmain", + id: "providers/openai/headers/Authorization", + }, + }, models: [{ id: "gpt-5", name: "gpt-5" }], }, - moonshot: { - baseUrl: "https://api.moonshot.cn/v1", - api: "openai-completions", - apiKey: { source: "exec", provider: "execmain", id: "providers/moonshot/apiKey" }, - models: [{ id: "moonshot-v1-8k", name: "moonshot-v1-8k" }], - }, }, }, }, @@ -545,24 +542,27 @@ describe("secrets audit", () => { }); }); - it("does not flag models.json marker values as plaintext", async () => { - await writeModelsProvider(); + it("exempts only known models.json apiKey markers from plaintext audit", async () => { + await writeJsonFile(fixture.modelsPath, { + providers: { + knownMarker: { + apiKey: OPENAI_API_KEY_MARKER, + }, + arbitraryAllCaps: { + apiKey: "ALLCAPS_SAMPLE", // pragma: allowlist secret + }, + }, + }); const report = await runSecretsAudit({ env: fixture.env }); expectModelsFinding(report, { code: "PLAINTEXT_FOUND", - jsonPath: "providers.openai.apiKey", + jsonPath: "providers.knownMarker.apiKey", present: false, }); - }); - - it("flags arbitrary all-caps models.json apiKey values as plaintext", async () => { - await writeModelsProvider({ apiKey: "ALLCAPS_SAMPLE" }); // pragma: allowlist secret - - const report = await runSecretsAudit({ env: fixture.env }); expectModelsFinding(report, { code: "PLAINTEXT_FOUND", - jsonPath: "providers.openai.apiKey", + jsonPath: "providers.arbitraryAllCaps.apiKey", }); }); @@ -660,53 +660,33 @@ describe("secrets audit", () => { expect(report.filesScanned).toContain(externalModelsPath); }); - it("does not flag $VAR shorthand env refs in auth profiles as plaintext", async () => { + it("classifies auth profile env shorthands as refs with or without explicit keyRef", async () => { writeAuthStore(fixture, { version: 1, profiles: { - "openai:default": { + "openai:dollar": { type: "api_key", provider: "openai", key: "$OPENAI_API_KEY", // pragma: allowlist secret }, - }, - }); - - const report = await runSecretsAudit({ env: fixture.env }); - expect( - hasFinding( - report, - (entry) => entry.code === "PLAINTEXT_FOUND" && entry.file === fixture.authStorePath, - ), - ).toBe(false); - }); - - it("does not flag ${VAR} env refs in auth profiles as plaintext", async () => { - writeAuthStore(fixture, { - version: 1, - profiles: { - "openai:default": { + "openai:braced": { type: "api_key", provider: "openai", key: "${OPENAI_API_KEY}", // pragma: allowlist secret }, - }, - }); - - const report = await runSecretsAudit({ env: fixture.env }); - expect( - hasFinding( - report, - (entry) => entry.code === "PLAINTEXT_FOUND" && entry.file === fixture.authStorePath, - ), - ).toBe(false); - }); - - it("still flags auth profile plaintext when an explicit ref is also configured", async () => { - writeAuthStore(fixture, { - version: 1, - profiles: { - "openai:default": { + "openai:dollar-with-ref": { + type: "api_key", + provider: "openai", + key: "$OPENAI_API_KEY", // pragma: allowlist secret + keyRef: { source: "env", id: "OPENAI_API_KEY" }, + }, + "openai:braced-with-ref": { + type: "api_key", + provider: "openai", + key: "${OPENAI_API_KEY}", // pragma: allowlist secret + keyRef: { source: "env", id: "OPENAI_API_KEY" }, + }, + "openai:plaintext-with-ref": { type: "api_key", provider: "openai", key: "sk-leftover-plaintext", // pragma: allowlist secret @@ -716,46 +696,13 @@ describe("secrets audit", () => { }); const report = await runSecretsAudit({ env: fixture.env }); - expect( - hasFinding( - report, - (entry) => - entry.code === "PLAINTEXT_FOUND" && - entry.file === fixture.authStorePath && - entry.jsonPath === "profiles.openai:default.key", - ), - ).toBe(true); + const authPlaintextPaths = report.findings + .filter((entry) => entry.code === "PLAINTEXT_FOUND" && entry.file === fixture.authStorePath) + .map((entry) => entry.jsonPath); + expect(authPlaintextPaths).toEqual(["profiles.openai:plaintext-with-ref.key"]); }); - it.each(["$OPENAI_API_KEY", "${OPENAI_API_KEY}"])( - "does not flag %s auth profile env refs when an explicit ref is also configured", - async (value) => { - writeAuthStore(fixture, { - version: 1, - profiles: { - "openai:default": { - type: "api_key", - provider: "openai", - key: value, - keyRef: { source: "env", id: "OPENAI_API_KEY" }, - }, - }, - }); - - const report = await runSecretsAudit({ env: fixture.env }); - expect( - hasFinding( - report, - (entry) => - entry.code === "PLAINTEXT_FOUND" && - entry.file === fixture.authStorePath && - entry.jsonPath === "profiles.openai:default.key", - ), - ).toBe(false); - }, - ); - - it("does not flag non-sensitive routing headers in openclaw config", async () => { + it("exempts direct routing headers but audits request headers in openclaw config", async () => { await writeJsonFile(fixture.configPath, { models: { providers: { @@ -766,32 +713,6 @@ describe("secrets audit", () => { headers: { "X-Proxy-Region": "us-west", }, - models: [{ id: "gpt-5", name: "gpt-5" }], - }, - }, - }, - }); - - const report = await runSecretsAudit({ env: fixture.env }); - expect( - hasFinding( - report, - (entry) => - entry.code === "PLAINTEXT_FOUND" && - entry.file === fixture.configPath && - entry.jsonPath === "models.providers.openai.headers.X-Proxy-Region", - ), - ).toBe(false); - }); - - it("keeps request headers in openclaw config covered by plaintext audit", async () => { - await writeJsonFile(fixture.configPath, { - models: { - providers: { - openai: { - baseUrl: "https://api.openai.com/v1", - api: "openai-completions", - apiKey: { source: "env", provider: "default", id: OPENAI_API_KEY_MARKER }, request: { headers: { "X-Proxy-Region": "us-west", @@ -804,6 +725,15 @@ describe("secrets audit", () => { }); const report = await runSecretsAudit({ env: fixture.env }); + expect( + hasFinding( + report, + (entry) => + entry.code === "PLAINTEXT_FOUND" && + entry.file === fixture.configPath && + entry.jsonPath === "models.providers.openai.headers.X-Proxy-Region", + ), + ).toBe(false); expect( hasFinding( report, @@ -815,60 +745,36 @@ describe("secrets audit", () => { ).toBe(true); }); - it("does not flag openclaw.json model provider apiKey marker values as plaintext", async () => { - await writeJsonFile(fixture.configPath, { - models: { - providers: { - lmstudio: { - baseUrl: "http://127.0.0.1:1234/v1", - api: "openai-completions", - apiKey: "lmstudio-local", - models: [{ id: "lmstudio-local", name: "lmstudio-local" }], - }, - ollama: { - baseUrl: "http://127.0.0.1:11434/v1", - api: "openai-completions", - apiKey: "ollama-local", - models: [{ id: "ollama-local", name: "ollama-local" }], - }, - openai: { - baseUrl: "https://api.openai.com/v1", - api: "openai-completions", - apiKey: "sk-real-plaintext", - models: [{ id: "gpt-5", name: "gpt-5" }], + it("exempts only known openclaw.json model provider apiKey markers", async () => { + for (const { apiKey, isPlaintext } of [ + { apiKey: "lmstudio-local", isPlaintext: false }, + { apiKey: "ollama-local", isPlaintext: false }, + { apiKey: "sk-real-plaintext", isPlaintext: true }, + ]) { + await writeJsonFile(fixture.configPath, { + models: { + providers: { + openai: { + baseUrl: "https://api.openai.com/v1", + api: "openai-completions", + apiKey, + models: [{ id: "gpt-5", name: "gpt-5" }], + }, }, }, - }, - }); + }); - const report = await runSecretsAudit({ env: fixture.env }); - expect( - hasFinding( - report, - (entry) => - entry.code === "PLAINTEXT_FOUND" && - entry.file === fixture.configPath && - entry.jsonPath === "models.providers.lmstudio.apiKey", - ), - ).toBe(false); - expect( - hasFinding( - report, - (entry) => - entry.code === "PLAINTEXT_FOUND" && - entry.file === fixture.configPath && - entry.jsonPath === "models.providers.ollama.apiKey", - ), - ).toBe(false); - expect( - hasFinding( - report, - (entry) => - entry.code === "PLAINTEXT_FOUND" && - entry.file === fixture.configPath && - entry.jsonPath === "models.providers.openai.apiKey", - ), - ).toBe(true); + const report = await runSecretsAudit({ env: fixture.env }); + expect( + hasFinding( + report, + (entry) => + entry.code === "PLAINTEXT_FOUND" && + entry.file === fixture.configPath && + entry.jsonPath === "models.providers.openai.apiKey", + ), + ).toBe(isPlaintext); + } }); it("scans .env in legacy .clawdbot state directory via automatic fallback", async () => { diff --git a/src/secrets/audit.ts b/src/secrets/audit.ts index 698b84da1679..ddda19a6b629 100644 --- a/src/secrets/audit.ts +++ b/src/secrets/audit.ts @@ -194,9 +194,10 @@ function collectConfigSecrets(params: { config: OpenClawConfig; configPath: string; collector: AuditCollector; + env: NodeJS.ProcessEnv; }): void { const defaults = params.config.secrets?.defaults; - for (const target of discoverConfigSecretTargets(params.config)) { + for (const target of discoverConfigSecretTargets(params.config, { env: params.env })) { if (!target.entry.includeInAudit) { continue; } @@ -236,14 +237,7 @@ function collectConfigSecrets(params: { } continue; } - - if (isNonSecretHeader) { - continue; - } - if (isModelMarker) { - continue; - } - if (!hasPlaintext) { + if (isNonSecretHeader || isModelMarker || !hasPlaintext) { continue; } addFinding(params.collector, { @@ -670,6 +664,7 @@ export async function runSecretsAudit( config, configPath, collector, + env, }); for (const agentDir of listAuthProfileStoreAgentDirs(config, stateDir)) { collectAuthStoreSecrets({ diff --git a/src/secrets/channel-contract-api.ts b/src/secrets/channel-contract-api.ts index c97a2d00a17b..882a05243eeb 100644 --- a/src/secrets/channel-contract-api.ts +++ b/src/secrets/channel-contract-api.ts @@ -196,9 +196,10 @@ export function loadChannelSecretContractApi(params: { config: OpenClawConfig; env?: NodeJS.ProcessEnv; loadablePluginOrigins?: ReadonlyMap; + bundledOnly?: boolean; }): BundledChannelSecretContractApi | undefined { const bundled = loadBundledChannelSecretContractApi(params.channelId); - if (bundled) { + if (bundled || params.bundledOnly) { return bundled; } // External contracts are considered only after bundled artifacts so core channels keep their diff --git a/src/secrets/target-registry-data.current-snapshot.test.ts b/src/secrets/target-registry-data.current-snapshot.test.ts index ca9afec9e74b..b4115c464e93 100644 --- a/src/secrets/target-registry-data.current-snapshot.test.ts +++ b/src/secrets/target-registry-data.current-snapshot.test.ts @@ -1,9 +1,18 @@ /** Tests target-registry data built from the current runtime snapshot. */ -import { beforeEach, describe, expect, it, vi } from "vitest"; +import fs from "node:fs"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { cleanupTrackedTempDirs, makeTrackedTempDir } from "../plugins/test-helpers/fs-fixtures.js"; + +const tempDirs: string[] = []; const metadataMocks = vi.hoisted(() => ({ listBundledPluginMetadata: vi.fn(), - resolvePluginMetadataSnapshot: vi.fn(() => ({ plugins: [] })), + resolvePluginMetadataSnapshot: vi.fn< + (params?: { config?: { plugins?: { load?: { paths?: string[] } } } }) => { + plugins: never[]; + } + >(() => ({ plugins: [] })), })); vi.mock("../plugins/bundled-plugin-metadata.js", () => ({ @@ -14,6 +23,37 @@ vi.mock("../plugins/plugin-metadata-snapshot.js", () => ({ resolvePluginMetadataSnapshot: metadataMocks.resolvePluginMetadataSnapshot, })); +function writeChannelContract(params: { + channelId: string; + pluginId: string; + targetId: string; + ownership: "channelConfigs" | "channels"; +}) { + const rootDir = makeTrackedTempDir("openclaw-target-registry-channel", tempDirs); + fs.writeFileSync( + path.join(rootDir, "secret-contract-api.cjs"), + `module.exports = { secretTargetRegistryEntries: [${JSON.stringify({ + id: params.targetId, + targetType: params.targetId, + configFile: "openclaw.json", + pathPattern: params.targetId, + secretShape: "secret_input", + expectedResolvedValue: "string", + includeInPlan: true, + includeInConfigure: true, + includeInAudit: true, + })}] };`, + "utf8", + ); + return { + id: params.pluginId, + origin: "config", + channels: params.ownership === "channels" ? [params.channelId] : [], + channelConfigs: params.ownership === "channelConfigs" ? { [params.channelId]: {} } : {}, + rootDir, + }; +} + describe("getSecretTargetRegistry metadata reuse", () => { beforeEach(() => { vi.resetModules(); @@ -25,6 +65,10 @@ describe("getSecretTargetRegistry metadata reuse", () => { metadataMocks.resolvePluginMetadataSnapshot.mockReturnValue({ plugins: [] }); }); + afterEach(() => { + cleanupTrackedTempDirs(tempDirs); + }); + it("allows configless runtime targets to reuse the lifecycle workspace", async () => { const { getSecretTargetRegistry } = await import("./target-registry-data.js"); @@ -96,4 +140,67 @@ describe("getSecretTargetRegistry metadata reuse", () => { expect(ids).toContain("channels.qqbot.clientSecret"); expect(ids).toContain("channels.qqbot.accounts.*.clientSecret"); }); + + it("builds config-scoped registries independently instead of reusing the singleton", async () => { + metadataMocks.resolvePluginMetadataSnapshot.mockImplementation( + (params?: { config?: { plugins?: { load?: { paths?: string[] } } } }) => { + const pluginId = params?.config?.plugins?.load?.paths?.[0] ?? "missing"; + return { + plugins: [ + { + id: pluginId, + origin: "config", + channels: [], + configContracts: { + secretInputs: { paths: [{ path: "credentials.token" }] }, + }, + }, + ], + } as never; + }, + ); + const { getSecretTargetRegistry } = await import("./target-registry-data.js"); + const firstConfig = { plugins: { load: { paths: ["first-plugin"] }, entries: {} } }; + const secondConfig = { plugins: { load: { paths: ["second-plugin"] }, entries: {} } }; + + const firstIds = getSecretTargetRegistry({ config: firstConfig, env: {} }).map( + (entry) => entry.id, + ); + const secondIds = getSecretTargetRegistry({ config: secondConfig, env: {} }).map( + (entry) => entry.id, + ); + + expect(firstIds).toContain("plugins.entries.first-plugin.config.credentials.token"); + expect(firstIds).not.toContain("plugins.entries.second-plugin.config.credentials.token"); + expect(secondIds).toContain("plugins.entries.second-plugin.config.credentials.token"); + expect(secondIds).not.toContain("plugins.entries.first-plugin.config.credentials.token"); + }); + + it("loads channel contracts from every supported ownership field", async () => { + const records = [ + writeChannelContract({ + channelId: "custom", + pluginId: "custom-primary", + targetId: "channels.custom.primaryToken", + ownership: "channels", + }), + writeChannelContract({ + channelId: "custom", + pluginId: "custom-secondary", + targetId: "channels.custom.secondaryToken", + ownership: "channelConfigs", + }), + ]; + metadataMocks.resolvePluginMetadataSnapshot.mockReturnValue({ plugins: records } as never); + const { getSecretTargetRegistry } = await import("./target-registry-data.js"); + + const ids = getSecretTargetRegistry({ + config: { plugins: { load: { paths: records.map((record) => record.rootDir) } } }, + env: {}, + }).map((entry) => entry.id); + + expect(ids).toEqual( + expect.arrayContaining(["channels.custom.primaryToken", "channels.custom.secondaryToken"]), + ); + }); }); diff --git a/src/secrets/target-registry-data.ts b/src/secrets/target-registry-data.ts index 9d7648ffb519..8e4a993e2646 100644 --- a/src/secrets/target-registry-data.ts +++ b/src/secrets/target-registry-data.ts @@ -1,4 +1,5 @@ /** Builds the static and plugin-derived registry of secret migration targets. */ +import type { OpenClawConfig } from "../config/types.openclaw.js"; import type { PluginManifestRecord } from "../plugins/manifest-registry.js"; import { resolvePluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js"; import { loadChannelSecretContractApiForRecord } from "./channel-contract-api.js"; @@ -92,10 +93,6 @@ function listChannelSecretTargetRegistryEntries( const entries: SecretTargetRegistryEntry[] = []; for (const record of channelPlugins) { - const channelIds = record.channels; - if (channelIds.length === 0) { - continue; - } try { const contractApi = loadChannelSecretContractApiForRecord(record); entries.push(...(contractApi?.secretTargetRegistryEntries ?? [])); @@ -445,15 +442,23 @@ const CORE_SECRET_TARGET_REGISTRY: SecretTargetRegistryEntry[] = [ let cachedSecretTargetRegistry: SecretTargetRegistryEntry[] | null = null; function loadSecretTargetRegistryFromPluginMetadata(params: { + config?: OpenClawConfig; env: NodeJS.ProcessEnv; preferPersisted?: boolean; }): SecretTargetRegistryEntry[] { const plugins = resolvePluginMetadataSnapshot({ + ...(params.config !== undefined ? { config: params.config } : {}), env: params.env, allowWorkspaceScopedCurrent: true, ...(params.preferPersisted !== undefined ? { preferPersisted: params.preferPersisted } : {}), }).plugins; - const channelPlugins = plugins.filter((record) => record.channels.length > 0); + const channelPlugins = plugins.filter( + (record) => + record.channels.length > 0 || + Object.keys(record.channelConfigs ?? {}).length > 0 || + Boolean(record.channelCatalogMeta?.id) || + Boolean(record.packageChannel?.id), + ); // Installed/workspace plugins own secret targets exactly like bundled ones // (#104320: the Exa split moved web providers out of bundled origin and their // targets vanished from the gateway's known-target registry). Entries stay @@ -487,6 +492,8 @@ export function getCoreSecretTargetRegistry(): SecretTargetRegistryEntry[] { /** Returns the process-cached registry including bundled plugin/channel metadata. */ /** Returns core plus plugin/channel secret target registry entries for the current metadata view. */ export function getSecretTargetRegistry(params?: { + config?: OpenClawConfig; + env?: NodeJS.ProcessEnv; sourceTree?: boolean; }): SecretTargetRegistryEntry[] { if (params?.sourceTree) { @@ -499,6 +506,14 @@ export function getSecretTargetRegistry(params?: { preferPersisted: false, }); } + if (params?.config) { + // Config-scoped plugin roots and policy are not process-stable. Compile these registries per + // request so one config cannot poison discovery for a later config in the same process. + return loadSecretTargetRegistryFromPluginMetadata({ + config: params.config, + env: params.env ?? process.env, + }); + } if (cachedSecretTargetRegistry) { return cachedSecretTargetRegistry; } diff --git a/src/secrets/target-registry-query.ts b/src/secrets/target-registry-query.ts index 2b41bb60d0f1..907177e61dc5 100644 --- a/src/secrets/target-registry-query.ts +++ b/src/secrets/target-registry-query.ts @@ -78,18 +78,15 @@ function buildConfigTargetIdIndex( return byId; } -function getCompiledSecretTargetRegistryState() { - if (compiledSecretTargetRegistryState) { - return compiledSecretTargetRegistryState; - } - const compiledSecretTargetRegistry = getSecretTargetRegistry().map(compileTargetRegistryEntry); +function compileSecretTargetRegistryState(registry: SecretTargetRegistryEntry[]) { + const compiledSecretTargetRegistry = registry.map(compileTargetRegistryEntry); const openClawCompiledSecretTargets = compiledSecretTargetRegistry.filter( (entry) => entry.configFile === "openclaw.json", ); const authProfilesCompiledSecretTargets = compiledSecretTargetRegistry.filter( (entry) => entry.configFile === "auth-profiles.json", ); - compiledSecretTargetRegistryState = { + return { authProfilesCompiledSecretTargets, authProfilesTargetsById: buildConfigTargetIdIndex(authProfilesCompiledSecretTargets), compiledSecretTargetRegistry, @@ -98,9 +95,20 @@ function getCompiledSecretTargetRegistryState() { openClawTargetsById: buildConfigTargetIdIndex(openClawCompiledSecretTargets), targetsByType: buildTargetTypeIndex(compiledSecretTargetRegistry), }; +} + +function getCompiledSecretTargetRegistryState() { + if (compiledSecretTargetRegistryState) { + return compiledSecretTargetRegistryState; + } + compiledSecretTargetRegistryState = compileSecretTargetRegistryState(getSecretTargetRegistry()); return compiledSecretTargetRegistryState; } +function getConfiguredSecretTargetRegistryState(config: OpenClawConfig, env: NodeJS.ProcessEnv) { + return compileSecretTargetRegistryState(getSecretTargetRegistry({ config, env })); +} + function getCompiledCoreOpenClawTargetState() { if (compiledCoreOpenClawTargetState) { return compiledCoreOpenClawTargetState; @@ -176,10 +184,31 @@ function configHasPluginEntries(config: OpenClawConfig): boolean { function getConfiguredChannelOpenClawTargets( config: OpenClawConfig, -): CompiledTargetRegistryEntry[] { - return Object.keys(config.channels ?? {}).flatMap( - (channelId) => getCompiledChannelOpenClawTargets(channelId) ?? [], - ); + env: NodeJS.ProcessEnv, +): CompiledTargetRegistryEntry[] | null { + const entries: CompiledTargetRegistryEntry[] = []; + for (const channelId of Object.keys(config.channels ?? {})) { + if (channelId === "defaults" || channelId === "modelByChannel" || channelId === "tools") { + continue; + } + const contract = loadChannelSecretContractApi({ + channelId, + config, + env, + bundledOnly: true, + }); + if (!contract) { + // External/custom channels may have multiple manifest owners. Only the full registry can + // prove their target set is complete; a config-scoped first-contract lookup cannot. + return null; + } + entries.push( + ...(contract.secretTargetRegistryEntries + ?.filter((entry) => entry.configFile === "openclaw.json") + .map(compileTargetRegistryEntry) ?? []), + ); + } + return entries; } function resolveDiscoveryEntries(params: { @@ -463,13 +492,12 @@ export function resolveConfigSecretTargetByPath(pathSegments: string[]): Resolve return null; } -/** - * Discovers configured secret-bearing values in openclaw.json using the full registry. - */ +/** Discovers configured secret-bearing values in openclaw.json. */ export function discoverConfigSecretTargets( config: OpenClawConfig, + options: { env?: NodeJS.ProcessEnv } = {}, ): DiscoveredConfigSecretTarget[] { - return discoverConfigSecretTargetsByIds(config); + return discoverConfigSecretTargetsByIds(config, undefined, options); } /** @@ -478,25 +506,33 @@ export function discoverConfigSecretTargets( export function discoverConfigSecretTargetsByIds( config: OpenClawConfig, targetIds?: Iterable, + options: { env?: NodeJS.ProcessEnv } = {}, ): DiscoveredConfigSecretTarget[] { + const env = options.env ?? process.env; const allowedTargetIds = normalizeAllowedTargetIds(targetIds); const coreState = getCompiledCoreOpenClawTargetState(); const hasOnlyCoreTargetIds = allowedTargetIds !== null && Array.from(allowedTargetIds).every((targetId) => coreState.knownTargetIds.has(targetId)); + const configuredChannelEntries = + !hasOnlyCoreTargetIds && !configHasPluginEntries(config) + ? getConfiguredChannelOpenClawTargets(config, env) + : null; const configuredEntries = hasOnlyCoreTargetIds ? coreState.openClawCompiledSecretTargets - : allowedTargetIds !== null && !configHasPluginEntries(config) - ? [...coreState.openClawCompiledSecretTargets, ...getConfiguredChannelOpenClawTargets(config)] + : configuredChannelEntries + ? [...coreState.openClawCompiledSecretTargets, ...configuredChannelEntries] : null; const configuredEntriesById = configuredEntries ? buildConfigTargetIdIndex(configuredEntries) : null; const canUseConfiguredEntries = configuredEntries !== null && - allowedTargetIds !== null && - Array.from(allowedTargetIds).every((targetId) => configuredEntriesById?.has(targetId)); - const registryState = canUseConfiguredEntries ? null : getCompiledSecretTargetRegistryState(); + (allowedTargetIds === null || + Array.from(allowedTargetIds).every((targetId) => configuredEntriesById?.has(targetId))); + const registryState = canUseConfiguredEntries + ? null + : getConfiguredSecretTargetRegistryState(config, env); const discoveryEntries = resolveDiscoveryEntries({ allowedTargetIds, defaultEntries: configuredEntries ?? registryState?.openClawCompiledSecretTargets ?? [], diff --git a/src/secrets/target-registry.fast-path.test.ts b/src/secrets/target-registry.fast-path.test.ts index 3b187099344b..f3c44a60e26f 100644 --- a/src/secrets/target-registry.fast-path.test.ts +++ b/src/secrets/target-registry.fast-path.test.ts @@ -1,12 +1,16 @@ -/** Tests that explicit channel secret target lookup avoids broad manifest rediscovery. */ +/** Tests that configured-only secret target lookup avoids broad manifest rediscovery. */ import { beforeEach, describe, expect, it, vi } from "vitest"; const { loadPluginManifestRegistryMock } = vi.hoisted(() => ({ loadPluginManifestRegistryMock: vi.fn(() => { - throw new Error("manifest registry should stay off the explicit channel target fast path"); + throw new Error("manifest registry should stay off configured-only target fast paths"); }), })); +const { getSecretTargetRegistryMock } = vi.hoisted(() => ({ + getSecretTargetRegistryMock: vi.fn(), +})); + const { loadBundledPluginPublicArtifactModuleSyncMock } = vi.hoisted(() => ({ loadBundledPluginPublicArtifactModuleSyncMock: vi.fn( ({ artifactBasename, dirName }: { artifactBasename: string; dirName: string }) => { @@ -60,7 +64,38 @@ vi.mock("../plugins/public-surface-loader.js", () => ({ loadBundledPluginPublicArtifactModuleSync: loadBundledPluginPublicArtifactModuleSyncMock, })); +vi.mock("./target-registry-data.js", async (importOriginal) => { + const actual = await importOriginal(); + const channelTarget = (id: string) => ({ + id, + targetType: id, + configFile: "openclaw.json" as const, + pathPattern: id, + secretShape: "secret_input" as const, + expectedResolvedValue: "string" as const, + includeInPlan: true, + includeInConfigure: true, + includeInAudit: true, + }); + getSecretTargetRegistryMock.mockImplementation( + (params?: { config?: { plugins?: { load?: { paths?: string[] } } } }) => { + const loadPath = params?.config?.plugins?.load?.paths?.[0]; + const channelEntries = + loadPath === "/plugins/custom-next" + ? [channelTarget("channels.customNext.token")] + : [ + channelTarget("channels.qqbot.clientSecret"), + channelTarget("channels.custom.primaryToken"), + channelTarget("channels.custom.secondaryToken"), + ]; + return [...actual.getCoreSecretTargetRegistry(), ...channelEntries]; + }, + ); + return { ...actual, getSecretTargetRegistry: getSecretTargetRegistryMock }; +}); + import { + discoverConfigSecretTargets, discoverConfigSecretTargetsByIds, resolveConfigSecretTargetByPath, resolvePlanTargetAgainstRegistry, @@ -70,6 +105,7 @@ describe("secret target registry fast path", () => { beforeEach(() => { loadPluginManifestRegistryMock.mockClear(); loadBundledPluginPublicArtifactModuleSyncMock.mockClear(); + getSecretTargetRegistryMock.mockClear(); }); it("resolves bundled channel targets by explicit channel id without manifest scans", () => { @@ -111,6 +147,52 @@ describe("secret target registry fast path", () => { expect(loadPluginManifestRegistryMock).not.toHaveBeenCalled(); }); + it("discovers all core and configured channel targets without loading plugin metadata", () => { + const targets = discoverConfigSecretTargets({ + gateway: { auth: { token: "gateway-token" } }, + channels: { telegram: { botToken: "telegram-token" } }, + }); + + const targetIds = targets.map((target) => target.entry.id); + expect(targetIds).toEqual( + expect.arrayContaining(["gateway.auth.token", "channels.telegram.botToken"]), + ); + expect(targetIds.some((targetId) => targetId.startsWith("plugins.entries."))).toBe(false); + expect(loadPluginManifestRegistryMock).not.toHaveBeenCalled(); + }); + + it("uses the complete registry for configured external and custom channels", () => { + const env = { HOME: "/audit-home" }; + const config = { + plugins: { load: { paths: ["/plugins/custom"] }, entries: {} }, + channels: { + qqbot: { clientSecret: "qqbot-secret" }, + custom: { + primaryToken: "primary-secret", + secondaryToken: "secondary-secret", + }, + }, + }; + const targets = discoverConfigSecretTargets(config, { env }); + + expect(targets.map((target) => target.entry.id)).toEqual( + expect.arrayContaining([ + "channels.qqbot.clientSecret", + "channels.custom.primaryToken", + "channels.custom.secondaryToken", + ]), + ); + expect(getSecretTargetRegistryMock).toHaveBeenLastCalledWith({ config, env }); + + const nextConfig = { + plugins: { load: { paths: ["/plugins/custom-next"] }, entries: {} }, + channels: { customNext: { token: "next-secret" } }, + }; + const nextTargets = discoverConfigSecretTargets(nextConfig, { env }); + expect(nextTargets.map((target) => target.entry.id)).toContain("channels.customNext.token"); + expect(getSecretTargetRegistryMock).toHaveBeenLastCalledWith({ config: nextConfig, env }); + }); + it("resolves channel plan targets without loading plugin metadata", () => { const target = resolvePlanTargetAgainstRegistry({ type: "channels.telegram.botToken", diff --git a/src/secrets/target-registry.test.ts b/src/secrets/target-registry.test.ts index f2297b025589..5e38506d238c 100644 --- a/src/secrets/target-registry.test.ts +++ b/src/secrets/target-registry.test.ts @@ -8,6 +8,7 @@ import { } from "../test-utils/talk-test-provider.js"; import { getCoreSecretTargetRegistry } from "./target-registry-data.js"; import { + discoverConfigSecretTargets, discoverConfigSecretTargetsByIds, resolveConfigSecretTargetByPath, resolveSecretPlanTargetByPathCore, @@ -101,6 +102,21 @@ describe("secret target registry", () => { "apiKey", ]); expect(fetchTarget?.entry?.id).toBe("plugins.entries.firecrawl.config.webFetch.apiKey"); + + const configuredTargets = discoverConfigSecretTargets({ + plugins: { + entries: { + exa: { + config: { + webSearch: { apiKey: "configured-plugin-key" }, + }, + }, + }, + }, + } as OpenClawConfig); + expect(configuredTargets.map((entry) => entry.entry.id)).toContain( + "plugins.entries.exa.config.webSearch.apiKey", + ); }); it("derives bundled plugin SecretInput contract target paths from plugin manifests", () => { From b46181bfc0ca6f3f2422d32d831986daaa97d275 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:31:55 -0700 Subject: [PATCH 058/165] fix(agent): post-tool timeout does not replay completed tools (#122516) * fix(agent): prevent replay after post-tool timeout * fix(agent): narrow settled tool assistant evidence --- ...ete-turn.settled-tool-continuation.test.ts | 11 +- ...omplete-turn.settled-tool-recovery.test.ts | 29 +---- ....incomplete-turn.terminal-evidence.test.ts | 122 +++++++++++++++--- ...un.prompt-timeout-fallback.test-support.ts | 100 ++++++++++++++ .../run/assistant-failure.test.ts | 65 +++++++++- .../run/assistant-failure.ts | 39 +++--- .../run/attempt-recovery.ts | 62 +++++---- .../run/attempt-terminal-evidence.ts | 8 ++ .../run/incomplete-turn-classification.ts | 1 + .../run/incomplete-turn-recovery.ts | 83 ++++++++---- .../run/settled-turn-finalization.ts | 50 ++----- .../run/terminal-resolution.ts | 19 ++- 12 files changed, 426 insertions(+), 163 deletions(-) diff --git a/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-continuation.test.ts b/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-continuation.test.ts index 046b690b3110..c115d3b7b99a 100644 --- a/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-continuation.test.ts +++ b/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-continuation.test.ts @@ -236,7 +236,7 @@ describe("runEmbeddedAgent incomplete-turn safety", () => { expectNoWarnMessageWith("settled post-tool turn lacked a final answer"); }); - it("records silent success when the settled-tool finalization completes empty", async () => { + it("surfaces an incomplete turn when a required settled-tool finalizer completes empty", async () => { const emptyStopAssistant = makeLastAssistant(); mockedClassifyFailoverReason.mockReturnValue(null); mockedRunEmbeddedAttempt.mockImplementationOnce(async (attemptParams) => { @@ -261,16 +261,19 @@ describe("runEmbeddedAgent incomplete-turn safety", () => { const result = await runEmbeddedAgent( makeRunParams("run-empty-stop-settled-tool-continuation-exhausted", { allowEmptyAssistantReplyAsSilent: true, + terminalReplyExpectation: "required", }), ); expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(2); - expect(result.payloads).toBeUndefined(); - expect(result.meta.error).toBeUndefined(); + expect(result.payloads?.[0]).toMatchObject({ isError: true }); + expect(result.payloads?.[0]?.text).toContain( + "some tool actions may have already been executed", + ); + expect(result.meta.error?.kind).toBe("incomplete_turn"); expect(result.meta.terminalReplyKind).toBeUndefined(); expect(result.meta.finalAssistantVisibleText).toBeUndefined(); expect(result.meta.finalAssistantRawText).toBeUndefined(); - expect(result.meta.stopReason).toBe("stop"); expectNoWarnMessageWith("empty response detected"); expectWarnMessageWith("settled-turn finalization completed without a visible answer"); }); diff --git a/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-recovery.test.ts b/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-recovery.test.ts index b3170e6e6e5a..c4d652bb38cc 100644 --- a/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-recovery.test.ts +++ b/src/agents/embedded-agent-runner/run.incomplete-turn.settled-tool-recovery.test.ts @@ -404,32 +404,17 @@ describe("runEmbeddedAgent incomplete-turn safety", () => { }); it("continues once after settled side-effecting tools finish without a final answer", async () => { - const acceptedSessionSpawns = [ - { runId: "child-run", childSessionKey: "agent:main:subagent:child" }, - ]; const toolUseAssistant = makeLastAssistant({ stopReason: "toolUse", content: [ { type: "toolCall", id: "tool_write", name: "write", arguments: { path: "note.txt" } }, { type: "toolCall", id: "tool_cron", name: "cron", arguments: { action: "add" } }, - { - type: "toolCall", - id: "tool_spawn", - name: "sessions_spawn", - arguments: { task: "follow up" }, - }, ], }); const settledToolResults = [ toolUseAssistant, { role: "toolResult", toolCallId: "tool_write", toolName: "write", isError: false }, { role: "toolResult", toolCallId: "tool_cron", toolName: "cron", isError: false }, - { - role: "toolResult", - toolCallId: "tool_spawn", - toolName: "sessions_spawn", - isError: false, - }, ] as unknown as EmbeddedRunAttemptResult["messagesSnapshot"]; mockedClassifyFailoverReason.mockReturnValue(null); mockedRunEmbeddedAttempt.mockImplementationOnce(async (attemptParams) => { @@ -437,15 +422,10 @@ describe("runEmbeddedAgent incomplete-turn safety", () => { return makeAttemptResult({ assistantTexts: [], latestMcpAppChannelView: { viewId: "view-after-tools" }, - toolMetas: [ - { toolName: "write", meta: "path=note.txt" }, - { toolName: "cron" }, - { toolName: "sessions_spawn" }, - ], + toolMetas: [{ toolName: "write", meta: "path=note.txt" }, { toolName: "cron" }], successfulNestedToolNames: ["read"], - acceptedSessionSpawns, successfulCronAdds: 1, - itemLifecycle: { startedCount: 3, completedCount: 3, activeCount: 0 }, + itemLifecycle: { startedCount: 2, completedCount: 2, activeCount: 0 }, messagesSnapshot: settledToolResults, lastAssistant: toolUseAssistant, currentAttemptAssistant: toolUseAssistant, @@ -475,10 +455,9 @@ describe("runEmbeddedAgent incomplete-turn safety", () => { expect(result.payloads?.[0]?.text).toBe("Write completed. Here is the final answer."); expect(result.latestMcpAppChannelView).toEqual({ viewId: "view-after-tools" }); expect(result.successfulCronAdds).toBe(1); - expect(result.acceptedSessionSpawns).toEqual(acceptedSessionSpawns); expect(result.meta.toolSummary).toEqual({ - calls: 3, - tools: ["write", "cron", "sessions_spawn"], + calls: 2, + tools: ["write", "cron"], failures: 0, }); expect(result.meta.agentMeta).toMatchObject({ diff --git a/src/agents/embedded-agent-runner/run.incomplete-turn.terminal-evidence.test.ts b/src/agents/embedded-agent-runner/run.incomplete-turn.terminal-evidence.test.ts index 6b6f6e45c759..8d3fc0cb9e7b 100644 --- a/src/agents/embedded-agent-runner/run.incomplete-turn.terminal-evidence.test.ts +++ b/src/agents/embedded-agent-runner/run.incomplete-turn.terminal-evidence.test.ts @@ -17,6 +17,35 @@ import { } from "./run/incomplete-turn-resolution.js"; import type { EmbeddedRunAttemptResult } from "./run/types.js"; +function makeSettledIdleWriteAttempt(options?: { + terminal?: EmbeddedRunAttemptResult["terminal"]; + stalePriorTurn?: boolean; +}) { + const toolUseAssistant = makeLastAssistant({ + stopReason: "toolUse", + content: [{ type: "toolCall", id: "tool_1", name: "write", arguments: {} }], + }); + const abortedAssistant = makeLastAssistant({ stopReason: "aborted", content: [] }); + return makeAttemptResult({ + terminal: options?.terminal ?? { kind: "timeout", phase: "prompt", source: "idle" }, + assistantTexts: [], + toolMetas: [{ toolName: "write", replaySafe: false }], + itemLifecycle: { startedCount: 1, completedCount: 1, activeCount: 0 }, + messagesSnapshot: [ + { role: "user", content: [{ type: "text", text: "old turn" }] }, + toolUseAssistant, + { role: "toolResult", toolCallId: "tool_1", toolName: "write", isError: false }, + ...(options?.stalePriorTurn + ? [{ role: "user", content: [{ type: "text", text: "current turn" }] }] + : []), + abortedAssistant, + ] as unknown as EmbeddedRunAttemptResult["messagesSnapshot"], + lastAssistant: abortedAssistant, + currentAttemptAssistant: abortedAssistant, + currentAttemptReplayMetadata: { hadPotentialSideEffects: true, replaySafe: false }, + }); +} + describe("runEmbeddedAgent incomplete-turn safety", () => { beforeEach(() => { resetRunIncompleteTurnOwnerMocks(); @@ -87,26 +116,81 @@ describe("runEmbeddedAgent incomplete-turn safety", () => { ).toBe(true); }); - it.each([ - { label: "aborted", aborted: true, timedOut: false, promptError: null }, - { label: "timed out", aborted: false, timedOut: true, promptError: null }, - { label: "prompt error", aborted: false, timedOut: false, promptError: new Error("closed") }, - ])("does not continue a $label tool-use terminal turn", ({ aborted, timedOut, promptError }) => { - const toolUseAssistant = makeLastAssistant({ - stopReason: "toolUse", - content: [{ type: "tool_use", id: "tool_1", name: "bash", input: {} }], - }); + it("continues an exactly settled current-turn tool batch after an idle prompt timeout", () => { const instruction = resolveSettledToolTerminalContinuationInstruction( - makeSettledContinuationParams( - { - assistantTexts: [], - toolMetas: [{ toolName: "bash" }], - itemLifecycle: { startedCount: 1, completedCount: 1, activeCount: 0 }, - lastAssistant: toolUseAssistant, - currentAttemptAssistant: toolUseAssistant, - }, - { aborted, timedOut, promptError }, - ), + makeSettledContinuationParams(makeSettledIdleWriteAttempt(), { + timedOut: true, + promptError: new Error("LLM idle timeout"), + }), + ); + + expect(instruction).toBe(SETTLED_TOOL_TERMINAL_CONTINUATION_INSTRUCTION); + }); + + it.each([ + { + label: "external abort", + terminal: { kind: "timeout", phase: "prompt", source: "external" } as const, + aborted: true, + timedOut: true, + }, + { + label: "runtime timeout", + terminal: { kind: "timeout", phase: "prompt", source: "runtime" } as const, + aborted: false, + timedOut: true, + }, + { + label: "run budget timeout", + terminal: { kind: "timeout", phase: "prompt", source: "run_budget" } as const, + aborted: false, + timedOut: true, + }, + { + label: "compaction timeout", + terminal: { kind: "timeout", phase: "compaction", source: "idle" } as const, + aborted: false, + timedOut: true, + }, + { + label: "tool execution timeout", + terminal: { kind: "timeout", phase: "tool_execution", source: "idle" } as const, + aborted: false, + timedOut: true, + }, + { + label: "timeout observation", + terminal: { kind: "timeout", phase: "tool_execution", source: "observation" } as const, + aborted: false, + timedOut: false, + }, + { + label: "prompt error without idle timeout", + terminal: { kind: "ok" } as const, + aborted: false, + timedOut: false, + promptError: new Error("closed"), + }, + ])( + "does not finalize settled tools after a $label", + ({ terminal, aborted, timedOut, promptError }) => { + const instruction = resolveSettledToolTerminalContinuationInstruction( + makeSettledContinuationParams(makeSettledIdleWriteAttempt({ terminal }), { + aborted, + timedOut, + promptError, + }), + ); + + expect(instruction).toBeNull(); + }, + ); + + it("does not use a settled prior-turn batch to authorize idle-timeout finalization", () => { + const instruction = resolveSettledToolTerminalContinuationInstruction( + makeSettledContinuationParams(makeSettledIdleWriteAttempt({ stalePriorTurn: true }), { + timedOut: true, + }), ); expect(instruction).toBeNull(); diff --git a/src/agents/embedded-agent-runner/run.prompt-timeout-fallback.test-support.ts b/src/agents/embedded-agent-runner/run.prompt-timeout-fallback.test-support.ts index 89651ae2d386..5fc40ac91108 100644 --- a/src/agents/embedded-agent-runner/run.prompt-timeout-fallback.test-support.ts +++ b/src/agents/embedded-agent-runner/run.prompt-timeout-fallback.test-support.ts @@ -4,7 +4,9 @@ import { makeModelFallbackCfg } from "../test-helpers/model-fallback-config-fixt import { makeAttemptResult } from "./run.overflow-compaction.fixture.js"; import { MockedFailoverError, + mockedBuildEmbeddedRunPayloads, mockedClassifyFailoverReason, + mockedGetApiKeyForModel, mockedRunEmbeddedAttempt, overflowBaseRunParams, resetSharedRunIntegrationHarnessMocks, @@ -58,4 +60,102 @@ describe("runEmbeddedAgent prompt timeout fallback handoff", () => { await expect(promise).rejects.toThrow("LLM request timed out."); expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(1); }); + + it("finalizes a settled write after an idle timeout without replaying the prompt", async () => { + const toolUseAssistant = { + role: "assistant" as const, + stopReason: "toolUse" as const, + provider: "openai", + model: "gpt-5.4", + content: [ + { + type: "toolCall", + id: "tool_write", + name: "write", + arguments: { path: "note.txt", content: "done" }, + }, + ], + }; + const abortedAssistant = { + role: "assistant" as const, + stopReason: "aborted" as const, + provider: "openai", + model: "gpt-5.4", + content: [], + }; + const finalAssistant = { + role: "assistant" as const, + stopReason: "stop" as const, + provider: "openai", + model: "gpt-5.4", + content: [{ type: "text", text: "The note was written once." }], + }; + mockedClassifyFailoverReason.mockReturnValue("timeout"); + mockedRunEmbeddedAttempt + .mockResolvedValueOnce( + makeAttemptResult({ + assistantTexts: [], + terminal: { kind: "timeout", phase: "prompt", source: "idle" }, + toolMetas: [{ toolName: "write", replaySafe: false }], + itemLifecycle: { startedCount: 1, completedCount: 1, activeCount: 0 }, + messagesSnapshot: [ + { role: "user", content: [{ type: "text", text: "Write note.txt" }] }, + toolUseAssistant, + { + role: "toolResult", + toolCallId: "tool_write", + toolName: "write", + isError: false, + }, + abortedAssistant, + ] as never, + lastAssistant: abortedAssistant as never, + currentAttemptAssistant: abortedAssistant as never, + currentAttemptReplayMetadata: { + hadPotentialSideEffects: true, + replaySafe: false, + }, + }), + ) + .mockResolvedValueOnce( + makeAttemptResult({ + assistantTexts: ["The note was written once."], + lastAssistant: finalAssistant as never, + currentAttemptAssistant: finalAssistant as never, + currentAttemptCompletedAssistant: finalAssistant as never, + }), + ); + mockedBuildEmbeddedRunPayloads + .mockReturnValueOnce([]) + .mockReturnValueOnce([{ text: "The note was written once." }]); + + const result = await runEmbeddedAgent({ + ...overflowBaseRunParams, + provider: "openai", + model: "gpt-5.4", + runId: "run-post-tool-idle-finalization", + config: makeModelFallbackCfg({ + agents: { + defaults: { + model: { + primary: "openai/gpt-5.4", + fallbacks: ["anthropic/claude-opus-4-6"], + }, + }, + }, + }), + }); + + expect(result.payloads).toEqual([{ text: "The note was written once." }]); + expect(result.meta.executionTrace?.fallbackUsed).toBe(false); + expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(2); + expect(mockedRunEmbeddedAttempt.mock.calls[1]?.[0]).toMatchObject({ + operation: "settled-tool-finalization", + disableTools: true, + skipPreparedUserTurnMessage: true, + prompt: + "The previous assistant turn completed its tool calls but did not produce a user-visible answer. Continue from the current transcript and produce the final user-visible answer now. Do not repeat completed tool calls or restart from scratch.", + }); + expect(mockedGetApiKeyForModel).toHaveBeenCalledTimes(1); + }); }); diff --git a/src/agents/embedded-agent-runner/run/assistant-failure.test.ts b/src/agents/embedded-agent-runner/run/assistant-failure.test.ts index c7b3765c207c..87d1828f7d17 100644 --- a/src/agents/embedded-agent-runner/run/assistant-failure.test.ts +++ b/src/agents/embedded-agent-runner/run/assistant-failure.test.ts @@ -110,6 +110,37 @@ function makeExhaustedCredentialFailureInput(options?: { replaySafe?: boolean }) }; } +function makeIdleTimeoutFailureInput(options?: { replaySafe?: boolean }) { + const fixture = makeExhaustedCredentialFailureInput(); + const replaySafe = options?.replaySafe === true; + const assistant = buildEmbeddedRunnerAssistant({ + provider: "anthropic", + model: "mock-1", + stopReason: "aborted", + }); + const replayMetadata = { + hadPotentialSideEffects: !replaySafe, + replaySafe, + }; + const attempt = makeEmbeddedRunnerAttempt({ + terminal: { kind: "timeout", phase: "prompt", source: "idle" }, + lastAssistant: assistant, + currentAttemptAssistant: assistant, + toolMetas: replaySafe ? [] : [{ toolName: "write", replaySafe: false }], + replayMetadata, + currentAttemptReplayMetadata: replayMetadata, + }); + fixture.input.attempt = attempt; + fixture.input.attemptAssistant = assistant; + fixture.input.currentAttemptAssistant = assistant; + fixture.input.terminalState = resolveEmbeddedRunAttemptTerminalState({ attempt, assistant }); + fixture.input.emptyErrorRetries = 0; + fixture.input.maybeRefreshRuntimeAuthForAuthError = vi.fn(async () => true); + fixture.input.maybeRetrySameModelRateLimit = vi.fn(async () => true); + fixture.input.advanceRateLimitAuthProfile = vi.fn(async () => true); + return fixture; +} + describe("handleEmbeddedAssistantFailure", () => { it("uses prepared OpenRouter ownership for custom-provider billing failures", async () => { const fixture = makeExhaustedCredentialFailureInput(); @@ -165,10 +196,11 @@ describe("handleEmbeddedAssistantFailure", () => { } fixture.input.attemptAssistant.errorCode = PROVIDER_POST_DISPATCH_AMBIGUITY_ERROR_CODE; fixture.input.attemptAssistant.errorMessage = "reasoning is required"; + fixture.input.resolveAuthProfileFailureReason = vi.fn(() => "timeout" as const); const outcome = await handleEmbeddedAssistantFailure(fixture.input); - expect(outcome.action).toBe("proceed"); + expect(outcome).toMatchObject({ action: "proceed", assistantProfileFailureReason: null }); expect(fixture.advanceAuthProfile).not.toHaveBeenCalled(); expect(fixture.maybeMarkAuthProfileFailure).not.toHaveBeenCalled(); expect(fixture.traceAttempts).toEqual([]); @@ -212,6 +244,37 @@ describe("handleEmbeddedAssistantFailure", () => { expect(fixture.traceAttempts).toEqual([]); }); + it("closes every failover retry after an idle timeout commits a write", async () => { + const fixture = makeIdleTimeoutFailureInput(); + + const outcome = await handleEmbeddedAssistantFailure(fixture.input); + + expect(outcome.action).toBe("proceed"); + expect(fixture.input.maybeRefreshRuntimeAuthForAuthError).not.toHaveBeenCalled(); + expect(fixture.input.maybeRetrySameModelRateLimit).not.toHaveBeenCalled(); + expect(fixture.advanceAuthProfile).not.toHaveBeenCalled(); + expect(fixture.input.advanceRateLimitAuthProfile).not.toHaveBeenCalled(); + expect(fixture.traceAttempts).toEqual([]); + }); + + it("keeps replay-safe idle timeout profile rotation available", async () => { + const fixture = makeIdleTimeoutFailureInput({ replaySafe: true }); + fixture.input.maybeRefreshRuntimeAuthForAuthError = vi.fn(async () => false); + + const outcome = await handleEmbeddedAssistantFailure(fixture.input); + + expect(outcome).toMatchObject({ action: "retry", lastRetryFailoverReason: "timeout" }); + expect(fixture.advanceAuthProfile).toHaveBeenCalledOnce(); + expect(fixture.traceAttempts).toEqual([ + { + provider: "anthropic", + model: "mock-1", + result: "rotate_profile", + stage: "assistant", + }, + ]); + }); + it("does not cache an exact credential-file failure from a fallback candidate", async () => { const previous = process.env.OPENCLAW_FALLBACK_SKIP_TTL_MS; process.env.OPENCLAW_FALLBACK_SKIP_TTL_MS = "60000"; diff --git a/src/agents/embedded-agent-runner/run/assistant-failure.ts b/src/agents/embedded-agent-runner/run/assistant-failure.ts index b9ce09fff744..8c721e4a94a3 100644 --- a/src/agents/embedded-agent-runner/run/assistant-failure.ts +++ b/src/agents/embedded-agent-runner/run/assistant-failure.ts @@ -23,6 +23,7 @@ import { import { log } from "../logger.js"; import type { TraceAttempt } from "../types.js"; import { handleAssistantFailover, isShortWindowRateLimitMessage } from "./assistant-failover.js"; +import { isCurrentAttemptReplaySafe } from "./attempt-terminal-evidence.js"; import { createFailoverDecisionLogger } from "./failover-observation.js"; import { resolveRunFailoverDecision } from "./failover-policy.js"; import { shouldRetrySilentErrorAssistantTurn } from "./incomplete-turn-recovery.js"; @@ -100,28 +101,10 @@ export async function handleEmbeddedAssistantFailure(input: { projectAgentRunAttemptTerminal(input.attempt.terminal); const terminalInterrupted = isEmbeddedRunTerminalInterrupted(input.terminalState.outcome); const { signalOwnedInterruption } = input.terminalState; - if (isReplayUnsafeAssistantError(input.attemptAssistant)) { - return buildOutcome(input, { - action: "proceed", - assistantProfileFailureReason: null, - }); - } const fallbackThinking = pickFallbackThinkingLevel({ message: input.attemptAssistant?.errorMessage, attempted: input.attemptedThinking, }); - if (fallbackThinking && !terminalInterrupted) { - log.warn( - `unsupported thinking level for ${input.provider}/${input.modelId}; retrying with ${fallbackThinking}`, - ); - return buildOutcome(input, { - action: "retry", - thinkLevel: fallbackThinking, - preserveSameModelRateLimitRetryCount: true, - assistantProfileFailureReason: null, - }); - } - const authFailure = isAuthAssistantError(input.attemptAssistant); const rateLimitFailure = isRateLimitAssistantError(input.attemptAssistant); const billingFailure = isBillingAssistantError(input.attemptAssistant); @@ -144,6 +127,26 @@ export async function handleEmbeddedAssistantFailure(input: { isShortWindowRateLimitMessage(input.attemptAssistant?.errorMessage), }, ); + const replayUnsafeAssistantError = isReplayUnsafeAssistantError(input.attemptAssistant); + if (replayUnsafeAssistantError || !isCurrentAttemptReplaySafe(input.attempt)) { + return buildOutcome(input, { + action: "proceed", + assistantProfileFailureReason: replayUnsafeAssistantError + ? null + : assistantProfileFailureReason, + }); + } + if (fallbackThinking && !terminalInterrupted) { + log.warn( + `unsupported thinking level for ${input.provider}/${input.modelId}; retrying with ${fallbackThinking}`, + ); + return buildOutcome(input, { + action: "retry", + thinkLevel: fallbackThinking, + preserveSameModelRateLimitRetryCount: true, + assistantProfileFailureReason, + }); + } const cloudCodeAssistFormatError = input.attempt.cloudCodeAssistFormatError; const imageDimensionError = parseImageDimensionError(input.attemptAssistant?.errorMessage ?? ""); const genericUnknownReasoningError = diff --git a/src/agents/embedded-agent-runner/run/attempt-recovery.ts b/src/agents/embedded-agent-runner/run/attempt-recovery.ts index b5034dcd076e..31696d7b0cb5 100644 --- a/src/agents/embedded-agent-runner/run/attempt-recovery.ts +++ b/src/agents/embedded-agent-runner/run/attempt-recovery.ts @@ -11,6 +11,7 @@ import type { EmbeddedAgentRunResult, TraceAttempt } from "../types.js"; import type { createUsageAccumulator } from "../usage-accumulator.js"; import type { prepareAndDispatchEmbeddedRunAttempt } from "./attempt-dispatch-preparation.js"; import type { normalizeEmbeddedRunAttempt } from "./attempt-normalization.js"; +import { isCurrentAttemptReplaySafe } from "./attempt-terminal-evidence.js"; import { buildEmbeddedRunBlockedResult } from "./blocked-run-result.js"; import { resolveCodexAppServerRecoveryRetry } from "./codex-app-server-recovery.js"; import { resolveCompactionLiveModelSelection } from "./compaction-live-model-selection.js"; @@ -110,6 +111,7 @@ export async function recoverEmbeddedRunAttempt(input: { timedOutByRunBudget, } = projectAgentRunAttemptTerminal(attempt.terminal); const terminalInterrupted = isEmbeddedRunTerminalInterrupted(terminalState.outcome); + const currentAttemptReplaySafe = isCurrentAttemptReplaySafe(attempt); const { signalOwnedInterruption } = terminalState; const assistantOverflowCandidate = currentAttemptCompletedAssistant !== undefined @@ -137,6 +139,40 @@ export async function recoverEmbeddedRunAttempt(input: { thinkLevel: updates?.thinkLevel ?? runtime.thinkLevel, }); + if (promptErrorSource === "hook:before_agent_run" && !terminalInterrupted) { + const errorText = formatErrorMessage(promptError); + const replayInvalid = resolveReplayInvalidForAttempt(); + setTerminalLifecycleMeta({ replayInvalid, livenessState: "blocked" }); + return { + action: "complete", + result: buildEmbeddedRunBlockedResult({ + text: errorText, + errorKind: "hook_block", + errorMessage: errorText, + durationMs: Date.now() - runInput.startedAtMs, + agentMeta: buildErrorAgentMeta({ + sessionId: sessionIdUsed, + sessionFile: sessionPromptState.sessionFile, + provider: preparedRuntime.provider, + model: preparedRuntime.model.id, + ...runtime.outerContextTokenMeta, + usageAccumulator: input.usageAccumulator, + lastRunPromptUsage: input.lastRunPromptUsage, + currentAttemptAssistant, + }), + attempt, + replayInvalid, + }), + }; + } + if (!currentAttemptReplaySafe) { + return { + action: "proceed", + shouldSurfaceCodexCompletionTimeout: + attempt.codexAppServerFailure?.kind === "turn_completion_idle_timeout" && timedOut, + }; + } + const requestedSelection = shouldSwitchToLiveModel({ cfg: params.config, sessionKey: runInput.resolvedSessionKey, @@ -255,32 +291,6 @@ export async function recoverEmbeddedRunAttempt(input: { }), }; } - if (promptErrorSource === "hook:before_agent_run" && !terminalInterrupted) { - const errorText = formatErrorMessage(promptError); - const replayInvalid = resolveReplayInvalidForAttempt(); - setTerminalLifecycleMeta({ replayInvalid, livenessState: "blocked" }); - return { - action: "complete", - result: buildEmbeddedRunBlockedResult({ - text: errorText, - errorKind: "hook_block", - errorMessage: errorText, - durationMs: Date.now() - runInput.startedAtMs, - agentMeta: buildErrorAgentMeta({ - sessionId: sessionIdUsed, - sessionFile: sessionPromptState.sessionFile, - provider: preparedRuntime.provider, - model: preparedRuntime.model.id, - ...runtime.outerContextTokenMeta, - usageAccumulator: input.usageAccumulator, - lastRunPromptUsage: input.lastRunPromptUsage, - currentAttemptAssistant, - }), - attempt, - replayInvalid, - }), - }; - } const hasRecoverableCodexAppServerTimeoutOutcome = Boolean( attempt.codexAppServerFailure && attempt.promptTimeoutOutcome, ); diff --git a/src/agents/embedded-agent-runner/run/attempt-terminal-evidence.ts b/src/agents/embedded-agent-runner/run/attempt-terminal-evidence.ts index 8f9852b4f63e..ea8b87ca5639 100644 --- a/src/agents/embedded-agent-runner/run/attempt-terminal-evidence.ts +++ b/src/agents/embedded-agent-runner/run/attempt-terminal-evidence.ts @@ -16,6 +16,14 @@ type ReplayMetadataAttempt = Pick< > & Partial>; +/** Uses current-attempt evidence when available and otherwise preserves fail-closed legacy state. */ +export function isCurrentAttemptReplaySafe( + attempt: Pick, +): boolean { + const replayMetadata = attempt.currentAttemptReplayMetadata ?? attempt.replayMetadata; + return replayMetadata.replaySafe && !replayMetadata.hadPotentialSideEffects; +} + /** * Marks whether retrying the attempt can safely replay the prompt. Concrete * tool-instance policy, async work, committed delivery, spawned sessions, and diff --git a/src/agents/embedded-agent-runner/run/incomplete-turn-classification.ts b/src/agents/embedded-agent-runner/run/incomplete-turn-classification.ts index fc532f8578a0..51e1b49a245f 100644 --- a/src/agents/embedded-agent-runner/run/incomplete-turn-classification.ts +++ b/src/agents/embedded-agent-runner/run/incomplete-turn-classification.ts @@ -33,6 +33,7 @@ export type IncompleteTurnAttempt = Pick< | "itemLifecycle" | "messagesSnapshot" | "replayMetadata" + | "currentAttemptReplayMetadata" | "terminal" | "toolMetas" > & diff --git a/src/agents/embedded-agent-runner/run/incomplete-turn-recovery.ts b/src/agents/embedded-agent-runner/run/incomplete-turn-recovery.ts index 10f4b24ed93d..dcaff3f76d58 100644 --- a/src/agents/embedded-agent-runner/run/incomplete-turn-recovery.ts +++ b/src/agents/embedded-agent-runner/run/incomplete-turn-recovery.ts @@ -7,7 +7,11 @@ import { hasCompletedMessagingToolDeliveryEvidence, } from "../delivery-evidence.js"; import { isZeroUsageEmptyStopAssistantTurn } from "../empty-assistant-turn.js"; -import { hasAsyncActivity, hasAttemptTerminalState } from "./attempt-terminal-evidence.js"; +import { + hasAsyncActivity, + hasAttemptTerminalState, + isCurrentAttemptReplaySafe, +} from "./attempt-terminal-evidence.js"; import { hasOnlySilentAssistantReply, hasPositiveOutputTokenUsage, @@ -60,9 +64,7 @@ export function shouldRetrySilentErrorAssistantTurn(params: { } // Current-attempt evidence avoids blocking on prior committed effects; older // harnesses retain the cumulative, fail-closed behavior. - const retryReplayMetadata = - params.attempt.currentAttemptReplayMetadata ?? params.attempt.replayMetadata; - if (retryReplayMetadata.hadPotentialSideEffects) { + if (!isCurrentAttemptReplaySafe(params.attempt)) { return false; } @@ -187,6 +189,27 @@ export function resolveReasoningOnlyRetryInstruction(params: { return REASONING_ONLY_RETRY_INSTRUCTION; } +type SettledToolCall = { id: string | null; name: string | null }; + +function readSettledToolCalls( + message: EmbeddedRunAttemptResult["currentAttemptAssistant"] | null | undefined, +): SettledToolCall[] { + if (!Array.isArray(message?.content)) { + return []; + } + return message.content.flatMap((item) => { + const block = item as { type?: unknown; id?: unknown; name?: unknown } | null; + return block?.type === "toolCall" + ? [ + { + id: typeof block.id === "string" ? block.id : null, + name: typeof block.name === "string" ? block.name : null, + }, + ] + : []; + }); +} + /** Builds one fresh continuation after settled tools ended without a visible final answer. */ export function resolveSettledToolTerminalContinuationInstruction(params: { provider?: string; @@ -201,8 +224,27 @@ export function resolveSettledToolTerminalContinuationInstruction(params: { timedOut: boolean; attempt: IncompleteTurnAttempt; }): string | null { - const assistant = params.attempt.currentAttemptAssistant ?? params.attempt.lastAssistant; const currentAttemptAssistant = params.attempt.currentAttemptAssistant; + const snapshot = params.attempt.messagesSnapshot ?? []; + const latestUserIndex = snapshot.findLastIndex((message) => message.role === "user"); + let assistant: EmbeddedRunAttemptResult["currentAttemptAssistant"] = currentAttemptAssistant; + let assistantIndex = assistant ? snapshot.indexOf(assistant) : -1; + if (assistantIndex <= latestUserIndex || readSettledToolCalls(assistant).length === 0) { + assistantIndex = snapshot.findLastIndex( + (message, index) => + index > latestUserIndex && + message.role === "assistant" && + readSettledToolCalls(message).length > 0, + ); + const assistantCandidate = assistantIndex >= 0 ? snapshot[assistantIndex] : undefined; + assistant = assistantCandidate?.role === "assistant" ? assistantCandidate : undefined; + } + const terminal = params.attempt.terminal; + const idlePromptTimeout = + terminal.kind === "timeout" && + terminal.phase === "prompt" && + terminal.source === "idle" && + params.attempt.currentAttemptReplayMetadata?.hadPotentialSideEffects === true; const emptyStopAfterSettledTools = Boolean( params.allowEmptyStopContinuation && currentAttemptAssistant?.stopReason === "stop" && @@ -220,25 +262,11 @@ export function resolveSettledToolTerminalContinuationInstruction(params: { // Idle is not proof of settlement: skipped or partially dispatched tools must // never be described as completed. Match each terminal call's id and owner to // its own current-batch result; a reported failure is settled, not successful. - const requestedToolCalls = Array.isArray(assistant?.content) - ? assistant.content.flatMap((item) => { - const block = item as { type?: unknown; id?: unknown; name?: unknown } | null; - return block?.type === "toolCall" - ? [ - { - id: typeof block.id === "string" ? block.id : null, - name: typeof block.name === "string" ? block.name : null, - }, - ] - : []; - }) - : []; + const requestedToolCalls = readSettledToolCalls(assistant); // Scan only results AFTER the terminal assistant: the snapshot spans the whole // session, and a prior turn's toolResult with a model-reused id would otherwise // prove "completion" for a batch that never dispatched. Assistant not found in // the snapshot fails closed to the existing incomplete-turn error. - const snapshot = params.attempt.messagesSnapshot ?? []; - const assistantIndex = assistant ? snapshot.indexOf(assistant) : -1; const settledToolResults = new Map( (assistantIndex >= 0 ? snapshot.slice(assistantIndex + 1) : []).flatMap((message) => { const result = message as { @@ -260,7 +288,9 @@ export function resolveSettledToolTerminalContinuationInstruction(params: { }), ); const allToolsProvenSettled = - params.attempt.itemLifecycle?.activeCount === 0 && + params.attempt.itemLifecycle.startedCount > 0 && + params.attempt.itemLifecycle.completedCount === params.attempt.itemLifecycle.startedCount && + params.attempt.itemLifecycle.activeCount === 0 && requestedToolCalls.length > 0 && requestedToolCalls.every( ({ id, name }) => @@ -284,13 +314,14 @@ export function resolveSettledToolTerminalContinuationInstruction(params: { params.payloadCount !== 0 || params.hasTerminalToolPresentation || params.aborted || - params.promptError != null || - params.timedOut || + ((params.promptError != null || + params.timedOut || + params.attempt.terminal.kind === "timeout") && + !idlePromptTimeout) || (assistant?.stopReason === "toolUse" ? !allToolsProvenSettled : !emptyStopAfterSettledTools) || hasUnsettledToolError || - (hasSettledTerminalToolFailure && - (hasAsyncActivity(params.attempt.toolMetas) || - hasAcceptedSessionSpawn(params.attempt.acceptedSessionSpawns))) || + hasAsyncActivity(params.attempt.toolMetas) || + hasAcceptedSessionSpawn(params.attempt.acceptedSessionSpawns) || params.attempt.clientToolCalls || params.attempt.yieldDetected || params.attempt.didSendDeterministicApprovalPrompt diff --git a/src/agents/embedded-agent-runner/run/settled-turn-finalization.ts b/src/agents/embedded-agent-runner/run/settled-turn-finalization.ts index 3aea8ff8d73c..192a0e5aeff8 100644 --- a/src/agents/embedded-agent-runner/run/settled-turn-finalization.ts +++ b/src/agents/embedded-agent-runner/run/settled-turn-finalization.ts @@ -107,34 +107,16 @@ export async function prepareTerminalWithSettledTurnFinalization(input: { prompt, noteLaneTaskProgress: input.finalization.noteLaneTaskProgress, }); - if (finalization.outcome === "empty") { - mergeUsageIntoAccumulator(input.terminalBase.usageAccumulator, finalization.result.usage); - lastRunPromptUsage = finalization.result.usage ?? lastRunPromptUsage; - log.warn( - `settled-turn finalization completed without a visible answer: runId=${runParams.runId} sessionId=${runParams.sessionId} ` + - `provider=${errorContext.provider}/${errorContext.model} — recording completed-empty outcome`, - ); - const emptyAssistant = finalization.result.assistant; - const completedEmptyAttempt = { - ...initial.attempt, - lastAssistant: emptyAssistant, - currentAttemptAssistant: emptyAssistant, - currentAttemptCompletedAssistant: emptyAssistant, - }; - return { - ...initial, - attempt: completedEmptyAttempt, - attemptAssistant: emptyAssistant, - currentAttemptCompletedAssistant: emptyAssistant, - prepared, - lastRunPromptUsage, - finalizationOutcome: "completed-empty" as const, - }; - } attempt = finalization.attempt; mergeUsageIntoAccumulator(input.terminalBase.usageAccumulator, attempt.attemptUsage); mergeAttemptRunStatsIntoAccumulator(input.terminalBase.usageAccumulator, attempt); lastRunPromptUsage = attempt.attemptUsage ?? lastRunPromptUsage; + if (finalization.outcome === "empty") { + log.warn( + `settled-turn finalization completed without a visible answer: runId=${runParams.runId} sessionId=${runParams.sessionId} ` + + `provider=${errorContext.provider}/${errorContext.model} — recording completed-empty outcome`, + ); + } // Successful isolated finalization owns a fresh terminal, never the original abort signal. const terminalState: EmbeddedRunTerminalState = { outcome: resolveEmbeddedRunAttemptTerminalOutcome({ @@ -164,7 +146,8 @@ export async function prepareTerminalWithSettledTurnFinalization(input: { sessionFileUsed: attempt.sessionFileUsed, prepared, lastRunPromptUsage, - finalizationOutcome: "answered" as const, + finalizationOutcome: + finalization.outcome === "empty" ? ("completed-empty" as const) : ("answered" as const), }; } catch (error) { log.warn( @@ -186,13 +169,7 @@ async function runPreparedSettledTurnFinalization(input: { harness: AgentHarness; prompt: string; noteLaneTaskProgress: () => void; -}): Promise< - | { outcome: "answered"; attempt: EmbeddedRunAttemptWithReceiptEvidence } - | { - outcome: "empty"; - result: AgentHarnessSettledTurnFinalizationResult; - } -> { +}): Promise<{ outcome: "answered" | "empty"; attempt: EmbeddedRunAttemptWithReceiptEvidence }> { return await withEmbeddedRunLaneProgressHeartbeat(input.noteLaneTaskProgress, async () => { const finalization = await runEmbeddedSettledTurnFinalizationWithBackend( { @@ -206,12 +183,10 @@ async function runPreparedSettledTurnFinalization(input: { input.settledAttempt, input.harness, ); - if (finalization.outcome === "empty") { - return finalization; - } return { - outcome: "answered", + outcome: finalization.outcome, attempt: buildSettledTurnFinalizationAttemptResult({ + outcome: finalization.outcome, result: finalization.result, settledAttempt: input.settledAttempt, prompt: input.prompt, @@ -222,13 +197,14 @@ async function runPreparedSettledTurnFinalization(input: { } function buildSettledTurnFinalizationAttemptResult(input: { + outcome: "answered" | "empty"; result: AgentHarnessSettledTurnFinalizationResult; settledAttempt: EmbeddedRunAttemptWithReceiptEvidence; prompt: string; agentHarnessId?: string; }): EmbeddedRunAttemptWithReceiptEvidence { const { result, settledAttempt } = input; - const text = resolveSettledTurnFinalizationText(result); + const text = input.outcome === "empty" ? "" : resolveSettledTurnFinalizationText(result); // Finalization replaces terminal ownership, not host-private facts from settled tools. // Keep those facts while replay, abort, and lifecycle state remain finalizer-local. return { diff --git a/src/agents/embedded-agent-runner/run/terminal-resolution.ts b/src/agents/embedded-agent-runner/run/terminal-resolution.ts index 9fc501936976..0e78982afa0d 100644 --- a/src/agents/embedded-agent-runner/run/terminal-resolution.ts +++ b/src/agents/embedded-agent-runner/run/terminal-resolution.ts @@ -63,6 +63,14 @@ type TerminalResolution = | { action: "retry" } | { action: "complete"; result: EmbeddedAgentRunResult }; +function requiresVisibleTerminalReply(runParams: TerminalRunParams): boolean { + return ( + runParams.terminalReplyExpectation === "required" || + (runParams.terminalReplyExpectation == null && + (runParams.trigger == null || runParams.trigger === "user" || runParams.trigger === "manual")) + ); +} + export function resolveSettledTurnFinalizationRequest(input: { runParams: TerminalRunParams; attempt: EmbeddedRunAttemptResult; @@ -131,12 +139,7 @@ export function resolveSettledTurnFinalizationRequest(input: { modelId: input.activeErrorContext.model, modelApi: input.modelApi, executionContract: input.executionContract, - allowEmptyStopContinuation: - input.runParams.terminalReplyExpectation === "required" || - (input.runParams.terminalReplyExpectation == null && - (input.runParams.trigger == null || - input.runParams.trigger === "user" || - input.runParams.trigger === "manual")), + allowEmptyStopContinuation: requiresVisibleTerminalReply(input.runParams), payloadCount, hasTerminalToolPresentation: input.hasTerminalToolPresentation, aborted: terminalAborted, @@ -311,8 +314,10 @@ export async function resolveEmbeddedRunTerminal(input: { ); return { action: "retry" }; } + const completedEmptyFinalization = input.settledTurnFinalizationOutcome === "completed-empty"; const incompleteTurnText = - emptyAssistantReplyIsSilent || input.settledTurnFinalizationOutcome === "completed-empty" + emptyAssistantReplyIsSilent || + (completedEmptyFinalization && !requiresVisibleTerminalReply(runParams)) ? null : resolveIncompleteTurnPayloadText({ payloadCount, From af3550df73f9d1846a02f76cae084246a48b1b98 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:41:17 -0700 Subject: [PATCH 059/165] fix(ui): confirm automation removal (#122505) Bind irreversible Cron removal to the current Gateway, admin scope, state object, and job revision across the confirmation modal. --- ui/src/e2e/cron-remove.e2e.test.ts | 106 ++++++++++++++++++++++++++++ ui/src/i18n/locales/en.ts | 3 + ui/src/pages/cron/cron-page.test.ts | 5 ++ ui/src/pages/cron/cron-page.ts | 58 ++++++++++++--- 4 files changed, 162 insertions(+), 10 deletions(-) create mode 100644 ui/src/e2e/cron-remove.e2e.test.ts diff --git a/ui/src/e2e/cron-remove.e2e.test.ts b/ui/src/e2e/cron-remove.e2e.test.ts new file mode 100644 index 000000000000..f2d49f8008a6 --- /dev/null +++ b/ui/src/e2e/cron-remove.e2e.test.ts @@ -0,0 +1,106 @@ +// Control UI tests own the destructive Automation removal flow through the rendered page. +import type { Page } from "playwright"; +import { expect, it } from "vitest"; +import { installMockGateway, waitForConfirmModal } from "../test-helpers/control-ui-e2e.ts"; +import { createControlUiE2eSuite } from "./control-ui-e2e-suite.test-support.ts"; + +const suite = createControlUiE2eSuite({ + name: "Control UI cron removal mocked Gateway E2E", + startServerBeforeBrowser: true, + unavailableMessage: (executablePath) => + `Playwright Chromium is not installed or cannot start at ${executablePath}.`, +}); + +const job = { + id: "nightly-digest", + name: "Nightly digest", + enabled: true, + createdAtMs: Date.parse("2026-08-11T08:00:00.000Z"), + updatedAtMs: Date.parse("2026-08-11T08:05:00.000Z"), + schedule: { kind: "every", everyMs: 60_000 }, + sessionTarget: "isolated", + wakeMode: "now", + payload: { kind: "agentTurn", message: "Summarize the overnight activity" }, + state: {}, +}; + +function cronListResponse(jobs: unknown[]) { + return { + jobs, + snapshotRevision: jobs.length > 0 ? "cron-remove-present" : "cron-remove-empty", + total: jobs.length, + offset: 0, + limit: 50, + hasMore: false, + nextOffset: null, + }; +} + +async function chooseRemove(page: Page) { + const menu = page.locator("wa-dropdown.cron-job-menu").first(); + await menu.locator(".cron-job-menu__trigger").click(); + await menu.locator('wa-dropdown-item[value="remove"]').click(); +} + +suite.define(() => { + it("confirms removal and rejects a decision captured before reconnect", async () => { + await suite.withPage( + { + locale: "en-US", + serviceWorkers: "block", + viewport: { height: 900, width: 1_280 }, + }, + async ({ page }) => { + const gateway = await installMockGateway(page, { + methodResponses: { + "cron.list": cronListResponse([job]), + "cron.runs": { entries: [], total: 0, offset: 0, limit: 50, hasMore: false }, + "cron.status": { enabled: true, jobs: 1, nextWakeAtMs: null }, + }, + }); + + const response = await page.goto(`${suite.server.baseUrl}cron`); + expect(response?.status()).toBe(200); + const row = page.locator(`[data-test-id="cron-row-${job.id}"]`); + await row.waitFor({ state: "visible", timeout: 10_000 }); + await row.locator(".cron-table__name-text").click(); + const detail = page.locator('.cron-page[data-panel-mode="job"]'); + await detail.waitFor({ state: "visible" }); + + await chooseRemove(page); + const cancelled = await waitForConfirmModal(page); + await expect(cancelled.textContent()).resolves.toContain(job.name); + await expect(cancelled.textContent()).resolves.toContain("permanently deletes"); + await expect(cancelled.textContent()).resolves.toContain("stops all future runs"); + expect(await cancelled.getByRole("checkbox").count()).toBe(0); + await expect.poll(async () => gateway.getRequests("cron.remove")).toHaveLength(0); + await cancelled.getByRole("button", { name: "Cancel" }).click(); + await expect.poll(async () => gateway.getRequests("cron.remove")).toHaveLength(0); + await detail.waitFor({ state: "visible" }); + await expect + .poll(() => detail.locator(".cron-detail-title").textContent()) + .toContain(job.name); + + await chooseRemove(page); + const stale = await waitForConfirmModal(page); + const socketCount = await gateway.getSocketCount(); + await gateway.closeLatest(1012, "Reconnect during automation removal confirmation"); + await expect.poll(() => gateway.getSocketCount()).toBeGreaterThan(socketCount); + await stale.getByRole("button", { name: "Remove" }).click(); + await expect.poll(async () => gateway.getRequests("cron.remove")).toHaveLength(0); + await row.waitFor({ state: "visible", timeout: 10_000 }); + + await chooseRemove(page); + const stable = await waitForConfirmModal(page); + const remove = stable.getByRole("button", { name: "Remove" }); + await expect.poll(() => remove.getAttribute("class")).toContain("danger"); + await gateway.setMethodResponse("cron.list", cronListResponse([])); + await remove.click(); + + await expect.poll(async () => gateway.getRequests("cron.remove")).toHaveLength(1); + expect((await gateway.getRequests("cron.remove"))[0]?.params).toEqual({ id: job.id }); + await expect.poll(() => row.count()).toBe(0); + }, + ); + }); +}); diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts index 7681cc675caa..0045edb14d75 100644 --- a/ui/src/i18n/locales/en.ts +++ b/ui/src/i18n/locales/en.ts @@ -5610,6 +5610,9 @@ export const en: TranslationMap = { resume: "Resume", clone: "Clone", remove: "Remove", + removeConfirmTitle: 'Remove "{name}"?', + removeConfirmMessage: + "This permanently deletes the automation and stops all future runs. This action cannot be undone.", more: "More actions", }, runNotStarted: { diff --git a/ui/src/pages/cron/cron-page.test.ts b/ui/src/pages/cron/cron-page.test.ts index 90f90ca6a94a..41eb1d7131fb 100644 --- a/ui/src/pages/cron/cron-page.test.ts +++ b/ui/src/pages/cron/cron-page.test.ts @@ -4,9 +4,12 @@ import { createDeferred } from "../../../../test/helpers/promise.js"; import type { GatewayBrowserClient, GatewayEventListener } from "../../api/gateway.ts"; import type { CronJob, CronJobsListResult } from "../../api/types.ts"; import type { ApplicationContext, ApplicationGatewaySnapshot } from "../../app/context.ts"; +import { showConfirmDialog } from "../../components/confirm-dialog.ts"; import type { CronState } from "../../lib/cron/index.ts"; import "./cron-page.ts"; +vi.mock("../../components/confirm-dialog.ts", () => ({ showConfirmDialog: vi.fn() })); + type CronTestPage = HTMLElement & { context: ApplicationContext; updateComplete: Promise; @@ -158,6 +161,7 @@ function createRequest() { afterEach(() => { document.body.replaceChildren(); + vi.mocked(showConfirmDialog).mockReset(); vi.restoreAllMocks(); }); @@ -443,6 +447,7 @@ describe("CronPage editor state sync", () => { const removeButton = Array.from(page.querySelectorAll(".cron-job-menu__item")).find( (item) => item.textContent?.trim() === "Remove", ) as HTMLButtonElement; + vi.mocked(showConfirmDialog).mockResolvedValueOnce(true); removeButton.click(); await waitForCronPage(() => expect(page.cron.cronEditingJobId).toBeNull()); await waitForCronPage(() => expect(page.cron.cronRunsScope).toBe("all")); diff --git a/ui/src/pages/cron/cron-page.ts b/ui/src/pages/cron/cron-page.ts index 8943c687f56a..285232809017 100644 --- a/ui/src/pages/cron/cron-page.ts +++ b/ui/src/pages/cron/cron-page.ts @@ -6,7 +6,9 @@ import { titleForRoute } from "../../app-navigation.ts"; import { applicationContext, type ApplicationContext } from "../../app/context.ts"; import { readGatewayOperatorAccess } from "../../app/operator-access.ts"; import { renderAgentScopeControl } from "../../components/agent-scope-control.ts"; +import { showConfirmDialog } from "../../components/confirm-dialog.ts"; import { renderSettingsWorkspace } from "../../components/settings-workspace.ts"; +import { t } from "../../i18n/index.ts"; import { watchAgentScope } from "../../lib/agents/index.ts"; import { addCronJob, @@ -286,6 +288,51 @@ class CronPage extends OpenClawLightDomElement { this.requestCronUpdate(); } + private async removeJob(job: CronJob) { + const context = this.context; + const cronState = this.cron; + const connectionScope = this.gateway.capture(); + const hadAdminAccess = this.canManageCron; + const selectedJob = cronState.cronJobs.find( + (entry) => entry.id === job.id && entry.updatedAtMs === job.updatedAtMs, + ); + if (!connectionScope || !hadAdminAccess || !selectedJob) { + return; + } + const selectedJobId = selectedJob.id; + const selectedJobRevision = selectedJob.updatedAtMs; + const selectedJobName = selectedJob.name; + const confirmed = await showConfirmDialog({ + title: t("cron.actions.removeConfirmTitle", { name: selectedJobName }), + message: t("cron.actions.removeConfirmMessage"), + confirmLabel: t("cron.actions.remove"), + danger: true, + }); + const currentJob = cronState.cronJobs.find((entry) => entry.id === selectedJobId); + // The modal yields while every owner can rotate. Reject stale decisions so + // an old row can never delete a replacement task on a new page or Gateway. + if ( + !confirmed || + this.context !== context || + this.cron !== cronState || + !this.gateway.isCurrent(connectionScope) || + !this.canManageCron || + !currentJob || + currentJob.updatedAtMs !== selectedJobRevision + ) { + return; + } + await this.runCronTask(async (current) => { + await removeCronJob(current, currentJob); + // Removing the selected task drops the panel back to overview; + // the runs scope must follow or recent activity stays empty. + if (current.cronRunsScope === "job" && current.cronRunsJobId === null) { + updateCronRunsFilter(current, { cronRunsScope: "all" }); + await loadCronRuns(current, null); + } + }); + } + private closePanel() { cancelCronEdit(this.cron); this.cron.cronCreateOpen = false; @@ -426,16 +473,7 @@ class CronPage extends OpenClawLightDomElement { }), onRun: (job, mode) => this.runCronAdminTask((cronState) => runCronJob(cronState, job.id, mode ?? "force")), - onRemove: (job) => - this.runCronAdminTask(async (cronState) => { - await removeCronJob(cronState, job); - // Removing the selected task drops the panel back to overview; - // the runs scope must follow or recent activity stays empty. - if (cronState.cronRunsScope === "job" && cronState.cronRunsJobId === null) { - updateCronRunsFilter(cronState, { cronRunsScope: "all" }); - await loadCronRuns(cronState, null); - } - }), + onRemove: (job) => void this.removeJob(job), onLoadMoreJobs: () => void this.runCronTask((cronState) => loadCronJobsPage(cronState, { append: true, tableFilters: true }), From 94c28e093d694fc8308c42f4a856f89fdf68cfc5 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:44:49 -0700 Subject: [PATCH 060/165] fix(test): route agent directory runs to owning shard (#122514) * fix(test): route agent directories to owner projects * fix(test): preserve invalid signal diagnostics --- scripts/run-vitest.mts | 89 ++-- scripts/test-projects.test-support.mts | 18 + src/agents/agent-tools.ts | 24 +- src/agents/bash-process-scope.test.ts | 44 ++ src/agents/bash-process-scope.ts | 22 + .../compact.hooks.harness.ts | 11 - .../prepared-compaction-runtime.ts | 3 +- .../run/attempt-context-engine-helpers.ts | 6 - .../run/attempt-finalize.ts | 8 +- .../run/attempt-history.ts | 8 +- .../run/attempt-prompt-helpers.ts | 2 +- .../run/attempt-session-prepare.ts | 8 +- .../attempt-spawn-workspace.test-support.ts | 17 +- .../run/attempt-system-prompt-prepare.ts | 2 +- .../attempt.context-engine-helpers.test.ts | 127 ++++- ...mpt.spawn-workspace.context-engine.test.ts | 434 +----------------- ....spawn-workspace.context-injection.test.ts | 4 +- .../run/compaction-runtime.ts | 2 +- .../harness/context-engine-lifecycle.test.ts | 133 +++++- test/scripts/run-vitest.test.ts | 36 +- test/scripts/test-projects.test.ts | 36 +- 21 files changed, 466 insertions(+), 568 deletions(-) create mode 100644 src/agents/bash-process-scope.test.ts create mode 100644 src/agents/bash-process-scope.ts diff --git a/scripts/run-vitest.mts b/scripts/run-vitest.mts index 4fffeff8a8ee..62206a6c63db 100644 --- a/scripts/run-vitest.mts +++ b/scripts/run-vitest.mts @@ -5,8 +5,10 @@ import fs from "node:fs"; import { createRequire } from "node:module"; import { constants as osConstants } from "node:os"; import path from "node:path"; -import type { Readable, Writable } from "node:stream"; -import { embeddedAgentVitestProjectOwners } from "../test/vitest/vitest.agents-paths.mjs"; +import { + agentVitestProjectOwners, + embeddedAgentVitestProjectOwners, +} from "../test/vitest/vitest.agents-paths.mjs"; import { toolingIsolatedTestFiles } from "../test/vitest/vitest.tooling-isolated-paths.mjs"; import { isUiTestTarget } from "../test/vitest/vitest.ui-paths.mjs"; import { boundaryTestFiles } from "../test/vitest/vitest.unit-paths.mjs"; @@ -35,6 +37,15 @@ type WatchdogStream = { on(event: string, listener: (...args: unknown[]) => void): unknown; off(event: string, listener: (...args: unknown[]) => void): unknown; }; +type NodeSignal = keyof typeof osConstants.signals; +type VitestOutputStream = { + setEncoding(encoding: "utf8"): unknown; + on(event: "data", listener: (chunk: string) => void): unknown; + on(event: "end", listener: () => void): unknown; +}; +type VitestOutputTarget = { + write(chunk: string): unknown; +}; const ANSI_CSI_PREFIX = `${String.fromCharCode(27)}[`; const ANSI_CSI_SUFFIX_RE = /^[0-?]*[ -/]*[@-~]/u; @@ -117,7 +128,10 @@ const VITEST_OPTIONS_WITH_VALUE = new Set([ "--retry", "--root", "-r", - "--sequence.shuffle.seed", + "--sequence", + "--sequence.hooks", + "--sequence.seed", + "--sequence.setupFiles", "--shard", "--silent", "--slowTestThreshold", @@ -138,7 +152,6 @@ const VITEST_DOTTED_OPTIONS_WITH_VALUE_PREFIXES = [ "--experimental.", "--outputFile.", "--retry.", - "--sequence.", "--typecheck.", ]; const UNBOUNDED_CONFIG_ONLY_OPTIONS = [ @@ -178,16 +191,17 @@ function isErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoExc return error instanceof Error && "code" in error && error.code === code; } -function isNodeSignal(signal: string): signal is NodeJS.Signals { +function isNodeSignal(signal: string): signal is NodeSignal { return Object.hasOwn(osConstants.signals, signal); } -function normalizeNodeSignal(signal: string | null): NodeJS.Signals | null { +function normalizeNodeSignal(signal: string | null): NodeSignal | null { if (!signal) { return null; } + const unknownSignalMessage = `child process exited with unknown signal: ${signal}`; if (!isNodeSignal(signal)) { - throw new Error(`child process exited with unknown signal: ${signal}`); + throw new Error(unknownSignalMessage); } return signal; } @@ -667,6 +681,18 @@ function isDelegableBroadProjectRouterTarget(arg: string, cwd: string): boolean ); } +function isPathAtOrUnder(value: string, root: string): boolean { + return value === root || value.startsWith(`${root}/`); +} + +function isOwnedAgentDirectoryTarget(arg: string, cwd: string, fsImpl: VitestPathFs): boolean { + const relative = toRepoRelativeArg(arg, cwd).replace(/\/+$/u, ""); + return ( + isPathAtOrUnder(relative, agentVitestProjectOwners.all.root) && + isExplicitDirectoryTargetArg(arg, cwd, fsImpl) + ); +} + function isExplicitProjectRouterTargetArg( arg: string, cwd = process.cwd(), @@ -683,7 +709,7 @@ function isExplicitProjectRouterTargetArg( } const filePath = path.isAbsolute(arg) ? arg : path.resolve(cwd, arg); return fsImpl.existsSync(filePath) - ? isDelegableBroadProjectRouterTarget(arg, cwd) + ? isDelegableBroadProjectRouterTarget(arg, cwd) || isOwnedAgentDirectoryTarget(arg, cwd, fsImpl) : path.extname(arg) === "" && /^(?:src|test|extensions|ui|packages|apps)\//u.test(toRepoRelativeArg(arg, cwd)); } @@ -810,42 +836,36 @@ function hasExplicitDisabledRunFlag(argv: string[]): boolean { return false; } -function hasSeparateVitestOptionValueArg(argv: string[]): boolean { - for (const arg of argv) { - if (arg === "--") { - return false; - } - if (optionConsumesNextArg(arg)) { - return true; - } - } - return false; -} - -function stripRunSubcommand(argv: string[]): string[] { - const stripped: string[] = []; +function resolveDelegatedVitestArgs(argv: string[]): string[] { + const positionalArgs: string[] = []; + const optionArgs: string[] = []; let canRemoveRunSubcommand = true; + let passthrough = false; for (let index = 0; index < argv.length; index += 1) { const arg = argv[index]; if (arg === undefined) { break; } if (arg === "--") { - stripped.push(arg); + passthrough = true; canRemoveRunSubcommand = false; continue; } - if (canRemoveRunSubcommand && optionConsumesNextArg(arg)) { - stripped.push(arg); + if (passthrough) { + optionArgs.push(arg); + continue; + } + if (optionConsumesNextArg(arg)) { + optionArgs.push(arg); const optionValue = argv[index + 1]; if (optionValue !== undefined) { + optionArgs.push(optionValue); index += 1; - stripped.push(optionValue); } continue; } - if (canRemoveRunSubcommand && arg.startsWith("-")) { - stripped.push(arg); + if (arg.startsWith("-")) { + optionArgs.push(arg); continue; } if (canRemoveRunSubcommand && arg === "run") { @@ -853,9 +873,9 @@ function stripRunSubcommand(argv: string[]): string[] { continue; } canRemoveRunSubcommand = false; - stripped.push(arg); + positionalArgs.push(arg); } - return stripped; + return optionArgs.length > 0 ? [...positionalArgs, "--", ...optionArgs] : positionalArgs; } function hasNonRunVitestSubcommand(argv: string[]): boolean { @@ -893,12 +913,11 @@ export function resolveTestProjectsDelegationArgs( resolveExplicitVitestMode(argv) === "watch" || hasNonRunVitestSubcommand(argv) || hasExplicitDisabledRunFlag(argv) || - hasSeparateVitestOptionValueArg(argv) || collectExplicitProjectRouterTargetArgs(argv, cwd).length === 0 ) { return null; } - return stripRunSubcommand(argv); + return resolveDelegatedVitestArgs(argv); } /** @@ -1138,8 +1157,8 @@ export function installVitestNoOutputWatchdog(params: { * Forwards child output while optionally suppressing complete stderr lines. */ function forwardVitestOutput( - stream: Readable | null, - target: Writable, + stream: VitestOutputStream | null, + target: VitestOutputTarget, shouldSuppressLine: (line: string) => boolean = () => false, ): void { if (!stream) { @@ -1185,7 +1204,7 @@ export function spawnWatchedVitestProcess({ label?: string; onNoOutputTimeout?: () => void; }) { - let forwardedSignal: NodeJS.Signals | null = null; + let forwardedSignal: NodeSignal | null = null; const child = spawnVitestProcess({ pnpmArgs, spawnParams, diff --git a/scripts/test-projects.test-support.mts b/scripts/test-projects.test-support.mts index 3331ec29516b..5b0386ad9b2d 100644 --- a/scripts/test-projects.test-support.mts +++ b/scripts/test-projects.test-support.mts @@ -1233,6 +1233,9 @@ function resolveExactSourceDirectoryTestTargets(targetArg: string, cwd: string) if (!isExactSourceDirectoryTarget(relative)) { return null; } + if (isCanonicalAgentOwnerDirectoryTarget(targetArg, cwd)) { + return [targetArg]; + } const prefix = `${relative}/`; const lightTargets = uniqueOrdered([ ...getUnitFastTestFiles(), @@ -1242,6 +1245,20 @@ function resolveExactSourceDirectoryTestTargets(targetArg: string, cwd: string) return lightTargets.length > 0 ? [...lightTargets, targetArg] : null; } +function isCanonicalAgentOwnerDirectoryTarget(targetArg: string, cwd: string) { + if (!isExistingDirectoryTarget(targetArg, cwd)) { + return false; + } + const kind = classifyTarget(targetArg, cwd); + if (kind === agentVitestProjectOwners.all.kind) { + return false; + } + const relative = toRepoRelativeTarget(targetArg, cwd).replace(/\/+$/u, ""); + return Object.values(agentVitestProjectOwners).some( + (owner) => owner.kind === kind && isPathAtOrUnder(relative, owner.root), + ); +} + /** * Finds explicit test path targets that do not match any known project plan. */ @@ -3650,6 +3667,7 @@ export function buildVitestRunPlans( const useCliTargetArgs = kind === "e2e" || kind === "packageDocker" || + grouped.every((targetArg) => isCanonicalAgentOwnerDirectoryTarget(targetArg, cwd)) || (kind === "default" && grouped.every((targetArg) => isFileLikeTarget(toRepoRelativeTarget(targetArg, cwd)))); const useWholeConfigTarget = grouped.some((targetArg) => diff --git a/src/agents/agent-tools.ts b/src/agents/agent-tools.ts index ede2fe371611..83797a9ffcdd 100644 --- a/src/agents/agent-tools.ts +++ b/src/agents/agent-tools.ts @@ -41,6 +41,7 @@ import { import type { AnyAgentTool } from "./agent-tools.types.js"; import { isApplyPatchAllowedForModel } from "./apply-patch-model-policy.js"; import type { AuthProfileStore } from "./auth-profiles/types.js"; +import { resolveProcessToolScopeKey } from "./bash-process-scope.js"; import type { ExecToolDefaults } from "./bash-tools.exec-types.js"; import type { ProcessToolDefaults } from "./bash-tools.process.js"; import { listChannelAgentTools } from "./channel-tools.js"; @@ -110,29 +111,6 @@ import { wrapToolWithGatewayCallerIdentity } from "./tools/gateway-caller-contex const MEMORY_FLUSH_ALLOWED_TOOL_NAMES = new Set(["read", "write"]); -/** Resolve the process-tool isolation key for exec/process session state. */ -export function resolveProcessToolScopeKey(params: { - scopeKey?: string; - sessionKey?: string; - sessionId?: string; - agentId?: string; -}): string | undefined { - const explicitScopeKey = params.scopeKey?.trim(); - if (explicitScopeKey) { - return explicitScopeKey; - } - const sessionKey = params.sessionKey?.trim(); - if (sessionKey) { - return sessionKey; - } - const sessionId = params.sessionId?.trim(); - if (sessionId) { - return sessionId; - } - const agentId = params.agentId?.trim(); - return agentId ? `agent:${agentId}` : undefined; -} - function applyModelProviderToolPolicy( toolsInput: AnyAgentTool[], params?: { diff --git a/src/agents/bash-process-scope.test.ts b/src/agents/bash-process-scope.test.ts new file mode 100644 index 000000000000..77fe8e8124b3 --- /dev/null +++ b/src/agents/bash-process-scope.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from "vitest"; +import { resolveProcessToolScopeKey } from "./bash-process-scope.js"; + +describe("resolveProcessToolScopeKey", () => { + it.each([ + { + name: "explicit scope before session identifiers", + params: { + scopeKey: " scope:explicit ", + sessionKey: "session-key", + sessionId: "session-id", + agentId: "main", + }, + expected: "scope:explicit", + }, + { + name: "session key before session and agent ids", + params: { + scopeKey: " ", + sessionKey: " session-key ", + sessionId: "session-id", + agentId: "main", + }, + expected: "session-key", + }, + { + name: "session id before agent id", + params: { sessionKey: "\t", sessionId: " session-id ", agentId: "main" }, + expected: "session-id", + }, + { + name: "agent id fallback", + params: { sessionId: "\n", agentId: " main " }, + expected: "agent:main", + }, + { + name: "blank inputs", + params: { scopeKey: " ", sessionKey: "\t", sessionId: "\n", agentId: " " }, + expected: undefined, + }, + ])("uses $name", ({ params, expected }) => { + expect(resolveProcessToolScopeKey(params)).toBe(expected); + }); +}); diff --git a/src/agents/bash-process-scope.ts b/src/agents/bash-process-scope.ts new file mode 100644 index 000000000000..85076b9143b6 --- /dev/null +++ b/src/agents/bash-process-scope.ts @@ -0,0 +1,22 @@ +/** Resolve the process-tool isolation key for exec/process session state. */ +export function resolveProcessToolScopeKey(params: { + scopeKey?: string; + sessionKey?: string; + sessionId?: string; + agentId?: string; +}): string | undefined { + const explicitScopeKey = params.scopeKey?.trim(); + if (explicitScopeKey) { + return explicitScopeKey; + } + const sessionKey = params.sessionKey?.trim(); + if (sessionKey) { + return sessionKey; + } + const sessionId = params.sessionId?.trim(); + if (sessionId) { + return sessionId; + } + const agentId = params.agentId?.trim(); + return agentId ? `agent:${agentId}` : undefined; +} diff --git a/src/agents/embedded-agent-runner/compact.hooks.harness.ts b/src/agents/embedded-agent-runner/compact.hooks.harness.ts index 7f5f93c58db0..5d7f9bc9d5ca 100644 --- a/src/agents/embedded-agent-runner/compact.hooks.harness.ts +++ b/src/agents/embedded-agent-runner/compact.hooks.harness.ts @@ -875,17 +875,6 @@ export async function loadCompactHooksHarness(): Promise<{ vi.doMock("../agent-tools.js", () => ({ createOpenClawCodingTools: createOpenClawCodingToolsMock, - resolveProcessToolScopeKey: ({ - scopeKey, - sessionKey, - sessionId, - agentId, - }: { - scopeKey?: string; - sessionKey?: string; - sessionId?: string; - agentId?: string; - }) => scopeKey ?? sessionKey ?? sessionId ?? (agentId ? `agent:${agentId}` : undefined), })); vi.doMock("./replay-history.js", () => ({ diff --git a/src/agents/embedded-agent-runner/prepared-compaction-runtime.ts b/src/agents/embedded-agent-runner/prepared-compaction-runtime.ts index 40b29f75b085..c6150fa11ccc 100644 --- a/src/agents/embedded-agent-runner/prepared-compaction-runtime.ts +++ b/src/agents/embedded-agent-runner/prepared-compaction-runtime.ts @@ -27,8 +27,9 @@ import { isReasoningTagProvider } from "../../utils/provider-utils.js"; import { createBundleLspToolRuntime } from "../agent-bundle-lsp-runtime.js"; import { createBundleMcpToolRuntime } from "../agent-bundle-mcp-tools.js"; import { resolveSessionAgentIds } from "../agent-scope.js"; -import { createOpenClawCodingTools, resolveProcessToolScopeKey } from "../agent-tools.js"; +import { createOpenClawCodingTools } from "../agent-tools.js"; import { listActiveProcessSessionReferences } from "../bash-process-references.js"; +import { resolveProcessToolScopeKey } from "../bash-process-scope.js"; import { makeBootstrapWarn, resolveBootstrapContextForRun, diff --git a/src/agents/embedded-agent-runner/run/attempt-context-engine-helpers.ts b/src/agents/embedded-agent-runner/run/attempt-context-engine-helpers.ts index bdb09493155a..8a374a76c841 100644 --- a/src/agents/embedded-agent-runner/run/attempt-context-engine-helpers.ts +++ b/src/agents/embedded-agent-runner/run/attempt-context-engine-helpers.ts @@ -12,12 +12,6 @@ import type { AgentMessage } from "../../runtime/index.js"; import { hasNonzeroUsage, normalizeUsage, type NormalizedUsage } from "../../usage.js"; import type { PromptCacheChange } from "../prompt-cache-observability.js"; import type { EmbeddedRunAttemptResult } from "./types.js"; -export { - assembleHarnessContextEngine as assembleAttemptContextEngine, - bootstrapHarnessContextEngine as runAttemptContextEngineBootstrap, - finalizeHarnessContextEngineTurn as finalizeAttemptContextEngineTurn, -} from "../../harness/context-engine-lifecycle.js"; - export type AttemptContextEngine = ContextEngine; type AttemptBootstrapContext = { diff --git a/src/agents/embedded-agent-runner/run/attempt-finalize.ts b/src/agents/embedded-agent-runner/run/attempt-finalize.ts index 6f1466d8c128..cb0442bccc87 100644 --- a/src/agents/embedded-agent-runner/run/attempt-finalize.ts +++ b/src/agents/embedded-agent-runner/run/attempt-finalize.ts @@ -20,6 +20,7 @@ import type { createCacheTrace } from "../../cache-trace.js"; import { countActiveToolExecutions } from "../../embedded-agent-subscribe.handlers.tools.js"; import { isSignalTimeoutReason } from "../../failover-error.js"; import { runAgentEndSideEffects } from "../../harness/agent-end-side-effects.js"; +import { finalizeHarnessContextEngineTurn } from "../../harness/context-engine-lifecycle.js"; import { runAgentCleanupStep } from "../../run-cleanup-timeout.js"; import type { AgentMessage } from "../../runtime/index.js"; import type { AgentSession, SessionManager } from "../../sessions/index.js"; @@ -28,10 +29,7 @@ import { runContextEngineMaintenance } from "../context-engine-maintenance.js"; import { log } from "../logger.js"; import { markActiveEmbeddedRunAbandoned, type EmbeddedAgentQueueHandle } from "../runs.js"; import { buildEmbeddedAgentEndContext } from "./agent-end-context.js"; -import { - finalizeAttemptContextEngineTurn, - type buildContextEnginePromptCacheInfo, -} from "./attempt-context-engine-helpers.js"; +import type { buildContextEnginePromptCacheInfo } from "./attempt-context-engine-helpers.js"; import { buildAfterTurnRuntimeContextFromUsage } from "./attempt-prompt-helpers.js"; import { shouldPersistCompletedBootstrapTurn } from "./attempt-thread-helpers.js"; import { @@ -253,7 +251,7 @@ export async function completeEmbeddedAttemptAfterTurn( sessionManager?: SessionManager; withSessionManagerRewriteLock: WithOwnedTranscriptWrite; }) => { - await finalizeAttemptContextEngineTurn({ + await finalizeHarnessContextEngineTurn({ contextEngine: activeContextEngine, promptError: Boolean(state.promptError), aborted: lifecycleState.aborted, diff --git a/src/agents/embedded-agent-runner/run/attempt-history.ts b/src/agents/embedded-agent-runner/run/attempt-history.ts index 41a30614d140..dd6e9e089853 100644 --- a/src/agents/embedded-agent-runner/run/attempt-history.ts +++ b/src/agents/embedded-agent-runner/run/attempt-history.ts @@ -24,6 +24,7 @@ import { import type { createPreparedEmbeddedAgentSettingsManager } from "../../agent-project-settings.js"; import type { createCacheTrace } from "../../cache-trace.js"; import { DEFAULT_CONTEXT_TOKENS } from "../../defaults.js"; +import { assembleHarnessContextEngine } from "../../harness/context-engine-lifecycle.js"; import type { AgentRuntimePlan } from "../../runtime-plan/types.js"; import type { AgentMessage } from "../../runtime/index.js"; import type { AgentSession, SessionManager } from "../../sessions/index.js"; @@ -32,10 +33,7 @@ import { resolveTranscriptPolicy, type TranscriptPolicy } from "../../transcript import { getHistoryLimitFromSessionKey, limitHistoryTurns } from "../history.js"; import { log } from "../logger.js"; import { sanitizeSessionHistory, validateReplayTurns } from "../replay-history.js"; -import { - assembleAttemptContextEngine, - type AttemptContextEngine, -} from "./attempt-context-engine-helpers.js"; +import type { AttemptContextEngine } from "./attempt-context-engine-helpers.js"; import type { resolveOrphanRepairPlan } from "./attempt-orphan-repair.js"; import { prependSystemPromptAddition } from "./attempt-prompt-helpers.js"; import { isRunnerToolCallBlockType } from "./attempt-tool-call-block-type.js"; @@ -575,7 +573,7 @@ export async function prepareEmbeddedAttemptHistory(input: { }); const messageBudget = Math.max(1, promptBudget - renderedPromptTokens); const transcriptReadFence = attempt.userTurnTranscriptRecorder?.getAdmissionReceipt(); - const assembled = await assembleAttemptContextEngine({ + const assembled = await assembleHarnessContextEngine({ contextEngine: input.activeContextEngine, sessionId: attempt.sessionId, sessionKey: attempt.sessionKey, diff --git a/src/agents/embedded-agent-runner/run/attempt-prompt-helpers.ts b/src/agents/embedded-agent-runner/run/attempt-prompt-helpers.ts index 499d06e87d83..a45092a64fd4 100644 --- a/src/agents/embedded-agent-runner/run/attempt-prompt-helpers.ts +++ b/src/agents/embedded-agent-runner/run/attempt-prompt-helpers.ts @@ -21,8 +21,8 @@ import { isCronSessionKey, isSubagentSessionKey } from "../../../routing/session import { shouldPreserveUserFacingSessionStateForInputProvenance } from "../../../sessions/input-provenance.js"; import { joinPresentTextSegments } from "../../../shared/text/join-segments.js"; import { truncateUtf16Safe } from "../../../utils.js"; -import { resolveProcessToolScopeKey } from "../../agent-tools.js"; import { listActiveProcessSessionReferences } from "../../bash-process-references.js"; +import { resolveProcessToolScopeKey } from "../../bash-process-scope.js"; import { resolveHeartbeatPromptForSystemPrompt } from "../../heartbeat-system-prompt.js"; import { wrapPluginSystemContextSection } from "../../hook-system-context-boundary.js"; import { diff --git a/src/agents/embedded-agent-runner/run/attempt-session-prepare.ts b/src/agents/embedded-agent-runner/run/attempt-session-prepare.ts index 55d43b1c6cf8..ee6516bf732d 100644 --- a/src/agents/embedded-agent-runner/run/attempt-session-prepare.ts +++ b/src/agents/embedded-agent-runner/run/attempt-session-prepare.ts @@ -19,6 +19,7 @@ import { } from "../../agent-settings.js"; import { toToolDefinitions } from "../../agent-tool-definition-adapter.js"; import { resolveUserTimezone } from "../../date-time.js"; +import { bootstrapHarnessContextEngine } from "../../harness/context-engine-lifecycle.js"; import { relocateCurrentRuntimeContextCarrierToTail } from "../../internal-runtime-context.js"; import type { AgentMessage } from "../../runtime/index.js"; import { guardSessionManager } from "../../session-tool-result-guard-wrapper.js"; @@ -36,10 +37,7 @@ import { log } from "../logger.js"; import { createEmbeddedAgentResourceLoader } from "../resource-loader.js"; import { applySystemPromptToSession } from "../system-prompt.js"; import { prepareEmbeddedAttemptClientTools } from "./attempt-client-tools.js"; -import { - type AttemptContextEngine, - runAttemptContextEngineBootstrap, -} from "./attempt-context-engine-helpers.js"; +import type { AttemptContextEngine } from "./attempt-context-engine-helpers.js"; import { resolveAttemptTranscriptPolicy } from "./attempt-history.js"; import { normalizeMessagesForLlmBoundary } from "./attempt-llm-boundary.js"; import { @@ -484,7 +482,7 @@ export async function prepareEmbeddedAttemptSessionManager(input: { input.onSessionManagerCreated(sessionManager); await input.withOwnedTranscriptWrite(async () => { - await runAttemptContextEngineBootstrap({ + await bootstrapHarnessContextEngine({ hadSessionFile: transcriptState.hasBootstrapTranscriptState, contextEngine: input.activeContextEngine, sessionId: attempt.sessionId, diff --git a/src/agents/embedded-agent-runner/run/attempt-spawn-workspace.test-support.ts b/src/agents/embedded-agent-runner/run/attempt-spawn-workspace.test-support.ts index bd43014ac263..2e4df4e01e80 100644 --- a/src/agents/embedded-agent-runner/run/attempt-spawn-workspace.test-support.ts +++ b/src/agents/embedded-agent-runner/run/attempt-spawn-workspace.test-support.ts @@ -6,7 +6,7 @@ import { normalizeLowercaseStringOrEmpty, normalizeOptionalLowercaseString, } from "@openclaw/normalization-core/string-coerce"; -import { expect, vi, type Mock } from "vitest"; +import { vi, type Mock } from "vitest"; import type { AssembleResult, BootstrapResult, @@ -667,17 +667,6 @@ vi.mock("../../cache-trace.js", () => ({ vi.mock("../../agent-tools.js", () => ({ createOpenClawCodingTools: (options?: { workspaceDir?: string; spawnWorkspaceDir?: string }) => hoisted.createOpenClawCodingToolsMock(options), - resolveProcessToolScopeKey: ({ - scopeKey, - sessionKey, - sessionId, - agentId, - }: { - scopeKey?: string; - sessionKey?: string; - sessionId?: string; - agentId?: string; - }) => scopeKey ?? sessionKey ?? sessionId ?? (agentId ? `agent:${agentId}` : undefined), resolveToolLoopDetectionConfig: () => undefined, })); @@ -1238,10 +1227,6 @@ export function createContextEngineBootstrapAndAssemble() { }; } -export function expectCalledWithSessionKey(mock: ReturnType, sessionKey: string) { - expect(mock).toHaveBeenCalledWith(expect.objectContaining({ sessionKey })); -} - const testModel = { api: "openai-completions", provider: "openai", diff --git a/src/agents/embedded-agent-runner/run/attempt-system-prompt-prepare.ts b/src/agents/embedded-agent-runner/run/attempt-system-prompt-prepare.ts index 8cbc9fb547b2..aa895dbe2c62 100644 --- a/src/agents/embedded-agent-runner/run/attempt-system-prompt-prepare.ts +++ b/src/agents/embedded-agent-runner/run/attempt-system-prompt-prepare.ts @@ -10,8 +10,8 @@ import { } from "../../../plugins/provider-runtime.js"; import { normalizeMessageChannel } from "../../../utils/message-channel.js"; import { isReasoningTagProvider } from "../../../utils/provider-utils.js"; -import { resolveProcessToolScopeKey } from "../../agent-tools.js"; import { listActiveProcessSessionReferences } from "../../bash-process-references.js"; +import { resolveProcessToolScopeKey } from "../../bash-process-scope.js"; import { buildBootstrapPromptWarningNotice, buildBootstrapTruncationReportMeta, diff --git a/src/agents/embedded-agent-runner/run/attempt.context-engine-helpers.test.ts b/src/agents/embedded-agent-runner/run/attempt.context-engine-helpers.test.ts index 3e8d263bfbd9..a54c5a033665 100644 --- a/src/agents/embedded-agent-runner/run/attempt.context-engine-helpers.test.ts +++ b/src/agents/embedded-agent-runner/run/attempt.context-engine-helpers.test.ts @@ -1,6 +1,12 @@ import { describe, expect, it } from "vitest"; import type { AssistantMessage } from "../../../llm/types.js"; -import { findLatestUncompactedAttemptUsageSnapshot } from "./attempt-context-engine-helpers.js"; +import type { AgentMessage } from "../../runtime/index.js"; +import { + buildContextEnginePromptCacheInfo, + buildLoopPromptCacheInfo, + findLatestUncompactedAttemptUsageSnapshot, + resolvePromptCacheTouchTimestamp, +} from "./attempt-context-engine-helpers.js"; const ASSISTANT_WITH_USAGE = { role: "assistant", @@ -41,3 +47,122 @@ describe("findLatestUncompactedAttemptUsageSnapshot", () => { ).toBeUndefined(); }); }); + +describe("context-engine prompt cache metadata", () => { + const seedMessage = { role: "user", content: "seed", timestamp: 1 } as AgentMessage; + + it("builds retention, last-call usage, and cache-touch metadata", () => { + expect( + buildContextEnginePromptCacheInfo({ + retention: "short", + lastCallUsage: { input: 10, output: 5, cacheRead: 40, cacheWrite: 2, total: 57 }, + lastCacheTouchAt: 123, + }), + ).toEqual({ + retention: "short", + lastCallUsage: { input: 10, output: 5, cacheRead: 40, cacheWrite: 2, total: 57 }, + lastCacheTouchAt: 123, + }); + }); + + it("omits metadata when no cache data is available", () => { + expect(buildContextEnginePromptCacheInfo({})).toBeUndefined(); + }); + + it("does not reuse a prior turn's usage when the current attempt has no assistant", () => { + const priorAssistant = { + role: "assistant", + content: "prior turn", + timestamp: 2, + usage: { input: 99, output: 7, cacheRead: 1234, total: 1340 }, + } as unknown as AgentMessage; + + expect( + buildLoopPromptCacheInfo({ + messagesSnapshot: [seedMessage, priorAssistant], + prePromptMessageCount: 2, + retention: "short", + }), + ).toEqual({ retention: "short" }); + }); + + it("derives live loop metadata from the current attempt assistant", () => { + const assistant = { + role: "assistant", + content: "tool use", + timestamp: "2026-04-16T16:49:59.536Z", + usage: { input: 1, output: 2, cacheRead: 39036, cacheWrite: 59934, total: 98973 }, + } as unknown as AgentMessage; + + const promptCache = buildLoopPromptCacheInfo({ + messagesSnapshot: [seedMessage, assistant], + prePromptMessageCount: 1, + retention: "short", + fallbackLastCacheTouchAt: 123, + }); + expect(promptCache?.retention).toBe("short"); + expect(promptCache?.lastCallUsage).toMatchObject({ + cacheRead: 39036, + cacheWrite: 59934, + total: 98973, + }); + expect(promptCache?.lastCacheTouchAt).toBe(Date.parse("2026-04-16T16:49:59.536Z")); + }); + + it("keeps the latest nonzero usage when an aborted assistant reports zeros", () => { + const completedAssistant = { + role: "assistant", + content: "tool use", + timestamp: "2026-04-16T16:49:59.536Z", + usage: { input: 38_333, output: 66, cacheRead: 120_320, total: 158_719 }, + } as unknown as AgentMessage; + const abortedAssistant = { + role: "assistant", + content: "", + timestamp: "2026-04-16T16:50:00.000Z", + stopReason: "aborted", + usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + } as unknown as AgentMessage; + + const promptCache = buildLoopPromptCacheInfo({ + messagesSnapshot: [seedMessage, completedAssistant, abortedAssistant], + prePromptMessageCount: 1, + retention: "short", + }); + expect(promptCache?.lastCallUsage).toMatchObject({ + input: 38_333, + cacheRead: 120_320, + total: 158_719, + }); + expect(promptCache?.lastCacheTouchAt).toBe(Date.parse("2026-04-16T16:49:59.536Z")); + }); + + it("falls back to the persisted cache touch when loop usage has no cache metrics", () => { + const assistant = { + role: "assistant", + content: "tool use", + timestamp: "2026-04-16T16:49:59.536Z", + usage: { input: 1, output: 2, total: 3 }, + } as unknown as AgentMessage; + + const promptCache = buildLoopPromptCacheInfo({ + messagesSnapshot: [seedMessage, assistant], + prePromptMessageCount: 1, + retention: "short", + fallbackLastCacheTouchAt: 123, + }); + expect(promptCache?.retention).toBe("short"); + expect(promptCache?.lastCallUsage?.total).toBe(3); + expect(promptCache?.lastCacheTouchAt).toBe(123); + }); + + it("derives a live cache touch timestamp for final afterTurn usage snapshots", () => { + expect( + resolvePromptCacheTouchTimestamp({ + lastCallUsage: { input: 1, output: 2, cacheRead: 39036, cacheWrite: 0, total: 39039 }, + assistantTimestamp: "2026-04-16T17:04:46.974Z", + fallbackLastCacheTouchAt: 123, + }), + ).toBe(Date.parse("2026-04-16T17:04:46.974Z")); + }); +}); diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts index 3f975fac7daf..f22e3a3734de 100644 --- a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts +++ b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts @@ -11,29 +11,16 @@ import { createSessionEntryWithTranscript, } from "../../../config/sessions/session-accessor.js"; import type { OpenClawConfig } from "../../../config/types.js"; -import { buildMemorySystemPromptAddition } from "../../../context-engine/delegate.js"; -import { - clearMemoryPluginState, - registerTestMemoryPromptBuilder, -} from "../../../plugins/memory-state.test-fixtures.js"; +import { clearMemoryPluginState } from "../../../plugins/memory-state.test-fixtures.js"; import { createUserTurnTranscriptRecorder } from "../../../sessions/user-turn-transcript.js"; import { projectAgentRunAttemptTerminal } from "../../agent-run-terminal-outcome.js"; import { makeAgentAssistantMessage } from "../../test-helpers/agent-message-fixtures.js"; -import { - type AttemptContextEngine, - buildLoopPromptCacheInfo, - assembleAttemptContextEngine, - buildContextEnginePromptCacheInfo, - finalizeAttemptContextEngineTurn, - resolvePromptCacheTouchTimestamp, - runAttemptContextEngineBootstrap, -} from "./attempt-context-engine-helpers.js"; +import type { AttemptContextEngine } from "./attempt-context-engine-helpers.js"; import { cleanupTempPaths, createDefaultEmbeddedSession, createContextEngineBootstrapAndAssemble, createContextEngineAttemptRunner, - expectCalledWithSessionKey, getHoisted, preloadRunEmbeddedAttemptForTests, resetEmbeddedAttemptHarness, @@ -43,14 +30,12 @@ import type { MidTurnPrecheckRequest } from "./midturn-precheck.js"; const hoisted = getHoisted(); const embeddedSessionId = "embedded-session"; -const sessionFile = "/tmp/session.jsonl"; const seedMessage = { role: "user", content: "seed", timestamp: 1 } as AgentMessage; const doneMessage = { role: "assistant", content: "done", timestamp: 2 } as unknown as AgentMessage; beforeAll(async () => { await preloadRunEmbeddedAttemptForTests(); }); -type AfterTurnPromptCacheCall = { runtimeContext?: { promptCache?: Record } }; type TrajectoryEvent = { type?: string; data?: Record }; type ToolResultGuardInstallParams = { midTurnPrecheck?: { @@ -156,67 +141,6 @@ function createTestContextEngine(params: Partial): Attempt } as AttemptContextEngine; } -async function runBootstrap( - sessionKey: string, - contextEngine: AttemptContextEngine, - overrides: Partial[0]> = {}, -) { - // Shared bootstrap harness keeps session identifiers stable across context - // engine implementations. - await runAttemptContextEngineBootstrap({ - hadSessionFile: true, - contextEngine, - sessionId: embeddedSessionId, - sessionKey, - sessionFile, - sessionManager: hoisted.sessionManager, - runtimeContext: {}, - runMaintenance: hoisted.runContextEngineMaintenanceMock, - warn: () => {}, - ...overrides, - }); -} - -async function runAssemble( - sessionKey: string, - contextEngine: AttemptContextEngine, - overrides: Partial[0]> = {}, -) { - return await assembleAttemptContextEngine({ - contextEngine, - sessionId: embeddedSessionId, - sessionKey, - messages: [seedMessage], - tokenBudget: 2048, - modelId: "gpt-test", - ...overrides, - }); -} - -async function finalizeTurn( - sessionKey: string, - contextEngine: AttemptContextEngine, - overrides: Partial[0]> = {}, -) { - await finalizeAttemptContextEngineTurn({ - contextEngine, - promptError: false, - aborted: false, - yieldAborted: false, - sessionIdUsed: embeddedSessionId, - sessionKey, - sessionFile, - messagesSnapshot: [doneMessage], - prePromptMessageCount: 0, - tokenBudget: 2048, - runtimeContext: {}, - runMaintenance: hoisted.runContextEngineMaintenanceMock, - sessionManager: hoisted.sessionManager, - warn: () => {}, - ...overrides, - }); -} - describe("runEmbeddedAttempt context engine sessionKey forwarding", () => { const sessionKey = "agent:main:guildchat:channel:test-ctx-engine"; const tempPaths: string[] = []; @@ -2678,24 +2602,6 @@ describe("runEmbeddedAttempt context engine sessionKey forwarding", () => { expect(events.slice(0, afterTurnIndex)).toContain("flush"); }); - it("forwards sessionKey to bootstrap, assemble, and afterTurn", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const afterTurn = vi.fn(async (_params: { sessionKey?: string }) => {}); - const contextEngine = createTestContextEngine({ - bootstrap, - assemble, - afterTurn, - }); - - await runBootstrap(sessionKey, contextEngine); - await runAssemble(sessionKey, contextEngine); - await finalizeTurn(sessionKey, contextEngine); - - expectCalledWithSessionKey(bootstrap, sessionKey); - expectCalledWithSessionKey(assemble, sessionKey); - expectCalledWithSessionKey(afterTurn, sessionKey); - }); - it("uses SQLite transcript messages for bootstrap without treating the marker as a file", async () => { const storeDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ctx-engine-sqlite-")); tempPaths.push(storeDir); @@ -2753,101 +2659,6 @@ describe("runEmbeddedAttempt context engine sessionKey forwarding", () => { expect(bootstrap).toHaveBeenCalled(); }); - it("forwards modelId to assemble", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const contextEngine = createTestContextEngine({ bootstrap, assemble }); - - await runBootstrap(sessionKey, contextEngine); - await runAssemble(sessionKey, contextEngine); - - expect(mockParams(assemble as MockCallSource, 0, "assemble params").model).toBe("gpt-test"); - }); - - it("forwards availableTools and citationsMode to assemble", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const contextEngine = createTestContextEngine({ bootstrap, assemble }); - - await runBootstrap(sessionKey, contextEngine); - await runAssemble(sessionKey, contextEngine, { - availableTools: new Set(["memory_search", "wiki_search"]), - citationsMode: "on", - }); - - expectFields(mockParams(assemble as MockCallSource, 0, "assemble params"), { - availableTools: new Set(["memory_search", "wiki_search"]), - citationsMode: "on", - }); - }); - - it("lets non-legacy engines opt into the active memory prompt helper", async () => { - registerTestMemoryPromptBuilder(({ availableTools, citationsMode }) => { - if (!availableTools.has("memory_search")) { - return []; - } - return [ - "## Memory Recall", - `tools=${[...availableTools].toSorted().join(",")}`, - `citations=${citationsMode ?? "auto"}`, - "", - ]; - }); - - const contextEngine = createTestContextEngine({ - assemble: async ({ messages, availableTools, citationsMode }) => ({ - messages, - estimatedTokens: messages.length, - systemPromptAddition: buildMemorySystemPromptAddition({ - availableTools: availableTools ?? new Set(), - citationsMode, - }), - }), - }); - - const result = await runAssemble(sessionKey, contextEngine, { - availableTools: new Set(["wiki_search", "memory_search"]), - citationsMode: "on", - }); - - const assembled = requireRecord(result, "assembled context"); - expect(assembled.estimatedTokens).toBe(1); - expect(assembled.systemPromptAddition).toBe( - "## Memory Recall\ntools=memory_search,wiki_search\ncitations=on", - ); - }); - - it("forwards sessionKey to ingestBatch when afterTurn is absent", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const ingestBatch = vi.fn( - async (_params: { sessionKey?: string; messages: AgentMessage[] }) => ({ ingestedCount: 1 }), - ); - - await finalizeTurn(sessionKey, createTestContextEngine({ bootstrap, assemble, ingestBatch }), { - messagesSnapshot: [seedMessage, doneMessage], - prePromptMessageCount: 1, - }); - - expectCalledWithSessionKey(ingestBatch, sessionKey); - }); - - it("forwards sessionKey to per-message ingest when ingestBatch is absent", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const ingest = vi.fn(async (_params: { sessionKey?: string; message: AgentMessage }) => ({ - ingested: true, - })); - - await finalizeTurn(sessionKey, createTestContextEngine({ bootstrap, assemble, ingest }), { - messagesSnapshot: [seedMessage, doneMessage], - prePromptMessageCount: 1, - }); - - expect(ingest).toHaveBeenCalledTimes(1); - expect(ingest).toHaveBeenCalledWith({ - message: doneMessage, - sessionId: embeddedSessionId, - sessionKey, - }); - }); - it("forwards silentExpected to the embedded subscription", async () => { await createContextEngineAttemptRunner({ contextEngine: createContextEngineBootstrapAndAssemble(), @@ -2904,247 +2715,6 @@ describe("runEmbeddedAttempt context engine sessionKey forwarding", () => { expect(result.didDeliverSourceReplyViaMessageTool).toBe(true); }); - it("skips maintenance when afterTurn fails", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const afterTurn = vi.fn(async () => { - throw new Error("afterTurn failed"); - }); - - await finalizeTurn(sessionKey, createTestContextEngine({ bootstrap, assemble, afterTurn })); - - expectCalledWithSessionKey(afterTurn, sessionKey); - expect( - hoisted.runContextEngineMaintenanceMock.mock.calls.some( - ([params]) => requireRecord(params, "maintenance params").reason === "turn", - ), - ).toBe(false); - }); - - it("runs startup maintenance for existing sessions even without bootstrap()", async () => { - const { assemble } = createContextEngineBootstrapAndAssemble(); - - await runBootstrap( - sessionKey, - createTestContextEngine({ - assemble, - maintain: async () => ({ - changed: false, - bytesFreed: 0, - rewrittenEntries: 0, - reason: "test maintenance", - }), - }), - ); - - expect( - hoisted.runContextEngineMaintenanceMock.mock.calls.some( - ([params]) => requireRecord(params, "maintenance params").reason === "bootstrap", - ), - ).toBe(true); - }); - - it("builds prompt-cache retention, last-call usage, and cache-touch metadata", () => { - expect( - buildContextEnginePromptCacheInfo({ - retention: "short", - lastCallUsage: { - input: 10, - output: 5, - cacheRead: 40, - cacheWrite: 2, - total: 57, - }, - lastCacheTouchAt: 123, - }), - ).toEqual({ - retention: "short", - lastCallUsage: { - input: 10, - output: 5, - cacheRead: 40, - cacheWrite: 2, - total: 57, - }, - lastCacheTouchAt: 123, - }); - }); - - it("omits prompt-cache metadata when no cache data is available", () => { - expect(buildContextEnginePromptCacheInfo({})).toBeUndefined(); - }); - - it("does not reuse a prior turn's usage when the current attempt has no assistant", () => { - const priorAssistant = { - role: "assistant", - content: "prior turn", - timestamp: 2, - usage: { - input: 99, - output: 7, - cacheRead: 1234, - total: 1340, - }, - } as unknown as AgentMessage; - const promptCache = buildLoopPromptCacheInfo({ - messagesSnapshot: [seedMessage, priorAssistant], - prePromptMessageCount: 2, - retention: "short", - }); - - expect(promptCache).toEqual({ retention: "short" }); - }); - - it("derives live loop prompt-cache info from the current attempt assistant", () => { - const toolUseAssistant = { - role: "assistant", - content: "tool use", - timestamp: "2026-04-16T16:49:59.536Z", - usage: { - input: 1, - output: 2, - cacheRead: 39036, - cacheWrite: 59934, - total: 98973, - }, - } as unknown as AgentMessage; - - const promptCache = buildLoopPromptCacheInfo({ - messagesSnapshot: [seedMessage, toolUseAssistant], - prePromptMessageCount: 1, - retention: "short", - fallbackLastCacheTouchAt: 123, - }); - expect(promptCache?.retention).toBe("short"); - expect(promptCache?.lastCallUsage?.cacheRead).toBe(39036); - expect(promptCache?.lastCallUsage?.cacheWrite).toBe(59934); - expect(promptCache?.lastCallUsage?.total).toBe(98973); - expect(promptCache?.lastCacheTouchAt).toBe(Date.parse("2026-04-16T16:49:59.536Z")); - }); - - it("keeps the latest nonzero usage when an aborted assistant reports zeros", () => { - const completedAssistant = { - role: "assistant", - content: "tool use", - timestamp: "2026-04-16T16:49:59.536Z", - usage: { input: 38_333, output: 66, cacheRead: 120_320, total: 158_719 }, - } as unknown as AgentMessage; - const abortedAssistant = { - role: "assistant", - content: "", - timestamp: "2026-04-16T16:50:00.000Z", - stopReason: "aborted", - usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, - } as unknown as AgentMessage; - - const promptCache = buildLoopPromptCacheInfo({ - messagesSnapshot: [seedMessage, completedAssistant, abortedAssistant], - prePromptMessageCount: 1, - retention: "short", - }); - - expect(promptCache?.lastCallUsage).toMatchObject({ - input: 38_333, - cacheRead: 120_320, - total: 158_719, - }); - expect(promptCache?.lastCacheTouchAt).toBe(Date.parse("2026-04-16T16:49:59.536Z")); - }); - - it("falls back to the persisted cache touch when loop usage has no cache metrics", () => { - const toolUseAssistant = { - role: "assistant", - content: "tool use", - timestamp: "2026-04-16T16:49:59.536Z", - usage: { - input: 1, - output: 2, - total: 3, - }, - } as unknown as AgentMessage; - - const promptCache = buildLoopPromptCacheInfo({ - messagesSnapshot: [seedMessage, toolUseAssistant], - prePromptMessageCount: 1, - retention: "short", - fallbackLastCacheTouchAt: 123, - }); - expect(promptCache?.retention).toBe("short"); - expect(promptCache?.lastCallUsage?.total).toBe(3); - expect(promptCache?.lastCacheTouchAt).toBe(123); - }); - - it("derives a live cache touch timestamp for final afterTurn usage snapshots", () => { - const lastCallUsage = { - input: 1, - output: 2, - cacheRead: 39036, - cacheWrite: 0, - total: 39039, - }; - - expect( - resolvePromptCacheTouchTimestamp({ - lastCallUsage, - assistantTimestamp: "2026-04-16T17:04:46.974Z", - fallbackLastCacheTouchAt: 123, - }), - ).toBe(Date.parse("2026-04-16T17:04:46.974Z")); - }); - - it("threads prompt-cache break observations into afterTurn", async () => { - const afterTurn = vi.fn(async (_params: AfterTurnPromptCacheCall) => {}); - - await finalizeTurn(sessionKey, createTestContextEngine({ afterTurn }), { - runtimeContext: { - promptCache: { - observation: { - broke: true, - previousCacheRead: 5000, - cacheRead: 2000, - changes: [{ code: "systemPrompt", detail: "system prompt digest changed" }], - }, - }, - }, - }); - - const afterTurnCall = afterTurn.mock.calls.at(0)?.[0]; - const runtimeContext = afterTurnCall?.runtimeContext; - const observation = runtimeContext?.promptCache?.observation as - | { broke?: boolean; previousCacheRead?: number; cacheRead?: number; changes?: unknown[] } - | undefined; - - const observationRecord = requireRecord(observation, "prompt cache observation"); - expectFields(observationRecord, { - broke: true, - previousCacheRead: 5000, - cacheRead: 2000, - }); - expect( - requireRecords(observationRecord.changes, "prompt cache observation changes").some( - (change) => change.code === "systemPrompt", - ), - ).toBe(true); - }); - - it("skips maintenance when ingestBatch fails", async () => { - const { bootstrap, assemble } = createContextEngineBootstrapAndAssemble(); - const ingestBatch = vi.fn(async () => { - throw new Error("ingestBatch failed"); - }); - - await finalizeTurn(sessionKey, createTestContextEngine({ bootstrap, assemble, ingestBatch }), { - messagesSnapshot: [seedMessage, doneMessage], - prePromptMessageCount: 1, - }); - - expectCalledWithSessionKey(ingestBatch, sessionKey); - expect( - hoisted.runContextEngineMaintenanceMock.mock.calls.some( - ([params]) => requireRecord(params, "maintenance params").reason === "turn", - ), - ).toBe(false); - }); - it("disposes the session even when teardown cleanup throws", async () => { const disposeMock = vi.fn(); const flushMock = vi.fn(async () => { diff --git a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-injection.test.ts b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-injection.test.ts index a7b58fbd450c..05308177d301 100644 --- a/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-injection.test.ts +++ b/src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-injection.test.ts @@ -4,10 +4,10 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; import { filterHeartbeatTranscriptArtifacts } from "../../../auto-reply/heartbeat-filter.js"; import { HEARTBEAT_PROMPT } from "../../../auto-reply/heartbeat.js"; import type { BootstrapContextRunKind } from "../../bootstrap-mode.js"; +import { assembleHarnessContextEngine } from "../../harness/context-engine-lifecycle.js"; import { limitHistoryTurns } from "../history.js"; import { buildEmbeddedMessageActionDiscoveryInput } from "../message-action-discovery-input.js"; import { - assembleAttemptContextEngine, type AttemptContextEngine, resolveAttemptBootstrapContext, } from "./attempt-context-engine-helpers.js"; @@ -232,7 +232,7 @@ describe("embedded attempt context injection", () => { HEARTBEAT_PROMPT, ); const limited = limitHistoryTurns(heartbeatFiltered, 1); - await assembleAttemptContextEngine({ + await assembleHarnessContextEngine({ contextEngine: { info: { id: "test", name: "Test", version: "0.0.1" }, ingest: async () => ({ ingested: true }), diff --git a/src/agents/embedded-agent-runner/run/compaction-runtime.ts b/src/agents/embedded-agent-runner/run/compaction-runtime.ts index cc3289924367..c54cd0ea4802 100644 --- a/src/agents/embedded-agent-runner/run/compaction-runtime.ts +++ b/src/agents/embedded-agent-runner/run/compaction-runtime.ts @@ -4,8 +4,8 @@ import { resolveCompactionSuccessorTranscript, type ContextEngineSessionTarget, } from "../../../context-engine/types.js"; -import { resolveProcessToolScopeKey } from "../../agent-tools.js"; import { listActiveProcessSessionReferences } from "../../bash-process-references.js"; +import { resolveProcessToolScopeKey } from "../../bash-process-scope.js"; import { buildEmbeddedCompactionRuntimeContext } from "../compaction-runtime-context.js"; import { compactContextEngineWithSafetyTimeout, diff --git a/src/agents/harness/context-engine-lifecycle.test.ts b/src/agents/harness/context-engine-lifecycle.test.ts index c48ecc35ad15..ef1bcb042c08 100644 --- a/src/agents/harness/context-engine-lifecycle.test.ts +++ b/src/agents/harness/context-engine-lifecycle.test.ts @@ -86,6 +86,52 @@ function uniqueConfiguredProofEngineId() { } describe("harness context engine lifecycle", () => { + it("forwards session keys across bootstrap, assemble, and afterTurn hooks", async () => { + const bootstrap = vi.fn(async () => ({ bootstrapped: true })); + const assemble = vi.fn(async (params: Parameters[0]) => ({ + messages: params.messages, + estimatedTokens: 0, + })); + const afterTurn = vi.fn(async () => {}); + const contextEngine = createContextEngine({ bootstrap, assemble, afterTurn }); + + await bootstrapHarnessContextEngine({ + hadSessionFile: true, + contextEngine, + sessionId: sessionParams.sessionId, + sessionKey: sessionParams.sessionKey, + sessionFile: sessionParams.sessionFile, + runMaintenance: async () => undefined, + warn: () => {}, + }); + await assembleHarnessContextEngine({ + contextEngine, + sessionId: sessionParams.sessionId, + sessionKey: sessionParams.sessionKey, + messages: [textMessage("user", "ask", 1)], + modelId: "gpt-test", + }); + await finalizeHarnessContextEngineTurn({ + contextEngine, + promptError: false, + aborted: false, + yieldAborted: false, + sessionIdUsed: sessionParams.sessionIdUsed, + sessionKey: sessionParams.sessionKey, + sessionFile: sessionParams.sessionFile, + messagesSnapshot: [textMessage("assistant", "done", 2)], + prePromptMessageCount: 0, + runMaintenance: async () => undefined, + warn: () => {}, + }); + + for (const hook of [bootstrap, assemble, afterTurn]) { + expect(hook).toHaveBeenCalledWith( + expect.objectContaining({ sessionKey: sessionParams.sessionKey }), + ); + } + }); + it("scopes async memory preparation to non-legacy assembly with sandbox context", async () => { const prepare = vi.fn(async ({ sandboxed }) => [ "## Prepared Memory", @@ -212,7 +258,15 @@ describe("harness context engine lifecycle", () => { const bootstrapRuntimeContext = { transcriptStorage: { kind: "sqlite" as const }, sessionTarget, - }; + promptCache: { + observation: { + broke: true, + previousCacheRead: 5000, + cacheRead: 2000, + changes: [{ code: "systemPrompt", detail: "system prompt digest changed" }], + }, + }, + } satisfies ContextEngineRuntimeContext; const engine = createContextEngine({ info: { id: engineId, @@ -238,6 +292,7 @@ describe("harness context engine lifecycle", () => { afterTurn: vi.fn(async (params) => { captured.push({ hook: "afterTurn", + runtimeContext: params.runtimeContext, runtimeSettings: params.runtimeSettings, sessionTarget: params.sessionTarget, }); @@ -282,6 +337,7 @@ describe("harness context engine lifecycle", () => { sessionKey: sessionParams.sessionKey, messages: [textMessage("user", "visible ask", 1)], tokenBudget: 2048, + runtimeContext: bootstrapRuntimeContext, providerId: "openai", requestedModelId: "openai/gpt-5.5", modelId: "anthropic/claude-sonnet-4-6", @@ -305,6 +361,7 @@ describe("harness context engine lifecycle", () => { ], prePromptMessageCount: 2, tokenBudget: 2048, + runtimeContext: bootstrapRuntimeContext, providerId: "openai", requestedModelId: "openai/gpt-5.5", modelId: "anthropic/claude-sonnet-4-6", @@ -349,6 +406,9 @@ describe("harness context engine lifecycle", () => { expect(captured.find((entry) => entry.hook === "afterTurn")?.sessionTarget).toEqual( sessionTarget, ); + expect(captured.find((entry) => entry.hook === "afterTurn")?.runtimeContext).toEqual( + bootstrapRuntimeContext, + ); expect(captured.find((entry) => entry.hook === "maintain")?.sessionTarget).toEqual( sessionTarget, ); @@ -555,10 +615,11 @@ describe("harness context engine lifecycle", () => { const ingestBatchCalls = (ingestBatch as unknown as { mock: { calls: unknown[][] } }).mock .calls; const ingestBatchParams = ingestBatchCalls[0]?.[0] as - | { isHeartbeat?: boolean; messages?: AgentMessage[] } + | { isHeartbeat?: boolean; messages?: AgentMessage[]; sessionKey?: string } | undefined; expect(ingestBatchParams?.messages).toEqual([turnUser, turnAssistant]); expect(ingestBatchParams?.isHeartbeat).toBe(true); + expect(ingestBatchParams?.sessionKey).toBe(sessionParams.sessionKey); }); it("forwards heartbeat state to per-message ingest fallbacks", async () => { @@ -586,11 +647,77 @@ describe("harness context engine lifecycle", () => { const ingestCalls = (ingest as unknown as { mock: { calls: unknown[][] } }).mock.calls; expect(ingestCalls).toHaveLength(2); for (const call of ingestCalls) { - const ingestParams = call[0] as { isHeartbeat?: boolean }; + const ingestParams = call[0] as { isHeartbeat?: boolean; sessionKey?: string }; expect(ingestParams.isHeartbeat).toBe(true); + expect(ingestParams.sessionKey).toBe(sessionParams.sessionKey); } }); + it.each(["afterTurn", "ingestBatch"] as const)( + "skips turn maintenance when %s fails", + async (failingHook) => { + const runMaintenance = vi.fn(async () => undefined); + const contextEngine = createContextEngine({ + afterTurn: + failingHook === "afterTurn" + ? vi.fn(async () => { + throw new Error("afterTurn failed"); + }) + : undefined, + ingestBatch: + failingHook === "ingestBatch" + ? vi.fn(async () => { + throw new Error("ingestBatch failed"); + }) + : undefined, + }); + + await finalizeHarnessContextEngineTurn({ + contextEngine, + promptError: false, + aborted: false, + yieldAborted: false, + sessionIdUsed: sessionParams.sessionIdUsed, + sessionKey: sessionParams.sessionKey, + sessionFile: sessionParams.sessionFile, + messagesSnapshot: [textMessage("assistant", "done", 1)], + prePromptMessageCount: 0, + runMaintenance, + warn: () => {}, + }); + + expect(runMaintenance).not.toHaveBeenCalled(); + }, + ); + + it("runs bootstrap maintenance for existing sessions without bootstrap()", async () => { + const runMaintenance = vi.fn(async () => undefined); + + await bootstrapHarnessContextEngine({ + hadSessionFile: true, + contextEngine: createContextEngine({ + bootstrap: undefined, + maintain: vi.fn(async () => ({ + changed: false, + bytesFreed: 0, + rewrittenEntries: 0, + })), + }), + sessionId: sessionParams.sessionId, + sessionKey: sessionParams.sessionKey, + sessionFile: sessionParams.sessionFile, + runMaintenance, + warn: () => {}, + }); + + expect(runMaintenance).toHaveBeenCalledWith( + expect.objectContaining({ + reason: "bootstrap", + sessionKey: sessionParams.sessionKey, + }), + ); + }); + it.each([ { promptError: true, aborted: false, yieldAborted: false }, { promptError: false, aborted: true, yieldAborted: false }, diff --git a/test/scripts/run-vitest.test.ts b/test/scripts/run-vitest.test.ts index b6e077bfabed..9bbc06a69326 100644 --- a/test/scripts/run-vitest.test.ts +++ b/test/scripts/run-vitest.test.ts @@ -348,11 +348,11 @@ describe("scripts/run-vitest", () => { [["run", file], [file]], [ ["run", file, "--reporter=verbose"], - [file, "--reporter=verbose"], + [file, "--", "--reporter=verbose"], ], [ ["--reporter=verbose", "run", file], - ["--reporter=verbose", file], + [file, "--", "--reporter=verbose"], ], [ ["run", file, "--", "--watch"], @@ -373,6 +373,7 @@ describe("scripts/run-vitest", () => { expect(resolveTestProjectsDelegationArgs([file])).toEqual([file]); expect(resolveTestProjectsDelegationArgs(["run", file, "--reporter=verbose"])).toEqual([ file, + "--", "--reporter=verbose", ]); }); @@ -381,7 +382,7 @@ describe("scripts/run-vitest", () => { expect(resolveTestProjectsDelegationArgs(["test/scripts"])).toEqual(["test/scripts"]); expect( resolveTestProjectsDelegationArgs(["run", "test/scripts", "--reporter=verbose"]), - ).toEqual(["test/scripts", "--reporter=verbose"]); + ).toEqual(["test/scripts", "--", "--reporter=verbose"]); expect(resolveTestProjectsDelegationArgs(["test/scripts/*.test.ts"])).toEqual([ "test/scripts/*.test.ts", ]); @@ -392,6 +393,15 @@ describe("scripts/run-vitest", () => { expect(resolveTestProjectsDelegationArgs([prefix])).toEqual([prefix]); }); + it("delegates owned agent directories with separate Vitest option values", () => { + const directory = "src/agents/embedded-agent-runner/run"; + + expect(resolveTestProjectsDelegationArgs([directory])).toEqual([directory]); + expect( + resolveTestProjectsDelegationArgs([directory, "--sequence.shuffle", "--sequence.seed", "3"]), + ).toEqual([directory, "--", "--sequence.shuffle", "--sequence.seed", "3"]); + }); + it("delegates mixed filters when an explicit file target is present", () => { expect( resolveTestProjectsDelegationArgs(["src/agents", "test/scripts/run-vitest.test.ts"]), @@ -420,15 +430,29 @@ describe("scripts/run-vitest", () => { ["--run=false", "test/scripts/run-vitest.test.ts"], ["--no-run", "test/scripts/run-vitest.test.ts"], ["--run", "false", "test/scripts/run-vitest.test.ts"], - ["--diff", "scripts/run-vitest.mjs"], - ["--testNamePattern", "run", "test/scripts/run-vitest.test.ts"], - ["run", "test/scripts/run-vitest.test.ts", "-t", "src"], ]; for (const argv of directArgvCases) { expect(resolveTestProjectsDelegationArgs(argv)).toBeNull(); } }); + it.each([ + [ + ["--diff", "scripts/run-vitest.mjs", "test/scripts/run-vitest.test.ts"], + ["test/scripts/run-vitest.test.ts", "--", "--diff", "scripts/run-vitest.mjs"], + ], + [ + ["--testNamePattern", "run", "test/scripts/run-vitest.test.ts"], + ["test/scripts/run-vitest.test.ts", "--", "--testNamePattern", "run"], + ], + [ + ["run", "test/scripts/run-vitest.test.ts", "-t", "src"], + ["test/scripts/run-vitest.test.ts", "--", "-t", "src"], + ], + ])("keeps option value %j out of project target classification", (argv, expected) => { + expect(resolveTestProjectsDelegationArgs(argv)).toEqual(expected); + }); + it("reports missing explicit test files before Vitest can silently ignore them", () => { const fsImpl = { existsSync: (filePath: string) => diff --git a/test/scripts/test-projects.test.ts b/test/scripts/test-projects.test.ts index 627ebd8ae902..d1366894e5c2 100644 --- a/test/scripts/test-projects.test.ts +++ b/test/scripts/test-projects.test.ts @@ -1048,21 +1048,29 @@ describe("scripts/test-projects changed-target routing", () => { ["src/agents/runtime-plan", "test/vitest/vitest.agents-support.config.ts"], ["src/agents/tools", "test/vitest/vitest.agents-tools.config.ts"], ])("routes focused agent directory %s to its owning shard", (directory, config) => { - const plans = buildVitestRunPlans([directory]); + expect(buildVitestRunPlans([directory])).toEqual([ + { + config, + forwardedArgs: [directory], + includePatterns: null, + watchMode: false, + }, + ]); + }); - expect(plans).toEqual( - expect.arrayContaining([ - { - config, - forwardedArgs: [], - includePatterns: [`${directory}/**/*.test.ts`], - watchMode: false, - }, - ]), - ); - expect(plans.map((plan) => plan.config)).not.toContain( - "test/vitest/vitest.agents-core.config.ts", - ); + it("keeps shuffle options on the single owning embedded-run shard", () => { + const directory = "src/agents/embedded-agent-runner/run"; + + expect( + buildVitestRunPlans([directory, "--", "--sequence.shuffle", "--sequence.seed", "3"]), + ).toEqual([ + { + config: "test/vitest/vitest.agents-embedded-agent-run.config.ts", + forwardedArgs: ["--sequence.shuffle", "--sequence.seed", "3", directory], + includePatterns: null, + watchMode: false, + }, + ]); }); it("splits the embedded-agent parent directory across every isolated harness", () => { From bfe1f33ea0ec3ccc5bb8738eb1dfc2b6f8dc0524 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:46:35 -0700 Subject: [PATCH 061/165] improve(ui): make Control UI feel native on mobile (#122492) * improve(ui): make Control UI feel native on mobile * fix(ui): keep coarse-pointer input floor text-scale aware * fix(ui): let self-sized controls opt out of the touch input floor * fix(ui): fold per-control coarse-pointer font floors into the shared touch floor --- ui/config/control-ui-hover-guard.ts | 38 ++++++++++++ ui/index.html | 3 + ui/src/app/bootstrap.test.ts | 28 +++++++++ ui/src/app/bootstrap.ts | 7 +++ .../app/control-ui-hover-guard.node.test.ts | 58 +++++++++++++++++++ .../components/form-controls.browser.test.ts | 4 ++ ui/src/styles/base.css | 26 +++++++++ ui/src/styles/chat/layout.css | 8 +-- ui/src/styles/chat/sidebar.css | 8 +-- ui/src/styles/components.css | 4 -- ui/src/styles/layout.css | 16 ++--- ui/src/styles/settings.css | 2 + ui/vite.config.ts | 6 ++ 13 files changed, 180 insertions(+), 28 deletions(-) create mode 100644 ui/config/control-ui-hover-guard.ts create mode 100644 ui/src/app/control-ui-hover-guard.node.test.ts diff --git a/ui/config/control-ui-hover-guard.ts b/ui/config/control-ui-hover-guard.ts new file mode 100644 index 000000000000..6f03bb826afb --- /dev/null +++ b/ui/config/control-ui-hover-guard.ts @@ -0,0 +1,38 @@ +import type { AnyNode, Plugin, Rule } from "postcss"; + +function isHoverGuarded(rule: Rule): boolean { + let ancestor: AnyNode | undefined = rule.parent; + while (ancestor) { + if (ancestor.type === "atrule" && ancestor.params.includes("hover:")) { + return true; + } + ancestor = ancestor.parent; + } + return false; +} + +export function controlUiHoverGuardPlugin(): Plugin { + return { + postcssPlugin: "control-ui-hover-guard", + Rule(rule, { AtRule }) { + if (!rule.selector.includes(":hover") || isHoverGuarded(rule)) { + return; + } + + const hoverSelectors = rule.selectors.filter((selector) => selector.includes(":hover")); + const otherSelectors = rule.selectors.filter((selector) => !selector.includes(":hover")); + const hoverRule = rule.clone(); + hoverRule.selectors = hoverSelectors; + const guard = new AtRule({ name: "media", params: "(hover: hover)" }); + guard.append(hoverRule); + + if (otherSelectors.length === 0) { + rule.replaceWith(guard); + return; + } + + rule.selectors = otherSelectors; + rule.after(guard); + }, + }; +} diff --git a/ui/index.html b/ui/index.html index fd112516b95e..131fc1622245 100644 --- a/ui/index.html +++ b/ui/index.html @@ -8,6 +8,9 @@ /> OpenClaw Control + + + diff --git a/ui/src/app/bootstrap.test.ts b/ui/src/app/bootstrap.test.ts index 173c9d16f768..a137178fc5c4 100644 --- a/ui/src/app/bootstrap.test.ts +++ b/ui/src/app/bootstrap.test.ts @@ -778,4 +778,32 @@ describe("normalizeInitialApplicationLocation", () => { window.history.replaceState({}, "", previousUrl); } }); + + it("synchronizes every theme-color meta with the resolved theme background", () => { + const previousSettings = loadSettings(); + const style = document.createElement("style"); + style.textContent = ':root[data-theme="light"] { --bg: #123456; }'; + const lightMeta = document.createElement("meta"); + lightMeta.name = "theme-color"; + lightMeta.media = "(prefers-color-scheme: light)"; + const darkMeta = document.createElement("meta"); + darkMeta.name = "theme-color"; + darkMeta.media = "(prefers-color-scheme: dark)"; + document.head.append(style, lightMeta, darkMeta); + saveSettings({ ...previousSettings, theme: "claw", themeMode: "light" }); + const runtime = bootstrapApplication({ sessionPathBuilderReady: deferred().promise }); + + try { + expect(lightMeta.content).toBe("#123456"); + expect(darkMeta.content).toBe("#123456"); + expect(lightMeta.hasAttribute("media")).toBe(false); + expect(darkMeta.hasAttribute("media")).toBe(false); + } finally { + runtime.stop(); + style.remove(); + lightMeta.remove(); + darkMeta.remove(); + saveSettings(previousSettings); + } + }); }); diff --git a/ui/src/app/bootstrap.ts b/ui/src/app/bootstrap.ts index 82426d02697f..678a6cff2180 100644 --- a/ui/src/app/bootstrap.ts +++ b/ui/src/app/bootstrap.ts @@ -76,6 +76,13 @@ function applyThemePresentation(settings: ReturnType): void root.style.colorScheme = root.dataset.themeMode; root.style.setProperty("--control-ui-text-scale", `${(settings.textScale ?? 100) / 100}`); syncCustomThemeStyleTag(settings.customTheme); + const background = getComputedStyle(root).getPropertyValue("--bg").trim(); + if (background) { + for (const meta of document.querySelectorAll('meta[name="theme-color"]')) { + meta.content = background; + meta.removeAttribute("media"); + } + } } function createApplicationTheme( diff --git a/ui/src/app/control-ui-hover-guard.node.test.ts b/ui/src/app/control-ui-hover-guard.node.test.ts new file mode 100644 index 000000000000..ac5d988be24a --- /dev/null +++ b/ui/src/app/control-ui-hover-guard.node.test.ts @@ -0,0 +1,58 @@ +// @vitest-environment node +import postcss, { type AtRule, type Rule } from "postcss"; +import { describe, expect, it } from "vitest"; +import { controlUiHoverGuardPlugin } from "../../config/control-ui-hover-guard.ts"; + +async function transform(css: string) { + return postcss([controlUiHoverGuardPlugin()]).process(css, { from: undefined }); +} + +function requireRule(node: unknown): Rule { + expect(node).toMatchObject({ type: "rule" }); + return node as Rule; +} + +function requireAtRule(node: unknown): AtRule { + expect(node).toMatchObject({ type: "atrule" }); + return node as AtRule; +} + +describe("Control UI hover guard", () => { + it("wraps a hover rule in a hover-capable media query", async () => { + const result = await transform(".button:hover { color: red; }"); + const guard = requireAtRule(result.root.first); + + expect(guard.params).toBe("(hover: hover)"); + expect(requireRule(guard.first).selector).toBe(".button:hover"); + }); + + it("splits mixed selector lists without moving non-hover selectors", async () => { + const result = await transform(".a:hover, .b:focus { color: red; }"); + const [original, guard] = result.root.nodes; + + expect(requireRule(original).selector).toBe(".b:focus"); + expect(requireRule(requireAtRule(guard).first).selector).toBe(".a:hover"); + }); + + it("does not double-wrap an already guarded hover rule", async () => { + const css = "@media (hover: hover) { .a:hover { color: red; } }"; + + expect((await transform(css)).css).toBe(css); + }); + + it("preserves an outer media condition around the hover guard", async () => { + const result = await transform("@media (max-width: 768px) { .a:hover { color: red; } }"); + const outer = requireAtRule(result.root.first); + const guard = requireAtRule(outer.first); + + expect(outer.params).toBe("(max-width: 768px)"); + expect(guard.params).toBe("(hover: hover)"); + expect(requireRule(guard.first).selector).toBe(".a:hover"); + }); + + it("passes CSS without hover selectors through byte-identically", async () => { + const css = ".button:focus { color: red; }\n"; + + expect((await transform(css)).css).toBe(css); + }); +}); diff --git a/ui/src/components/form-controls.browser.test.ts b/ui/src/components/form-controls.browser.test.ts index 4a567d358113..8fdc2658c3f3 100644 --- a/ui/src/components/form-controls.browser.test.ts +++ b/ui/src/components/form-controls.browser.test.ts @@ -485,6 +485,7 @@ describeBrowserLayout("app chrome interaction styles", () => { Mobile navigation
+
Child session 3m @@ -509,6 +510,7 @@ describeBrowserLayout("app chrome interaction styles", () => { coarsePointer: matchMedia("(hover: none) and (pointer: coarse)").matches, agentFilter: fontSize(".sidebar-agent-menu__filter input"), fileSearch: fontSize(".file-view__search input"), + settingsSearch: fontSize(".settings-sidebar__search-input"), navItem: fontSize(".shell--mobile-nav .nav-item"), }; }); @@ -520,6 +522,7 @@ describeBrowserLayout("app chrome interaction styles", () => { coarsePointer: true, agentFilter: 16, fileSearch: 16, + settingsSearch: 16, navItem: 12, }); @@ -531,6 +534,7 @@ describeBrowserLayout("app chrome interaction styles", () => { expect(scaled.childName).toBeCloseTo(12 * 1.4, 1); expect(scaled.childTrail).toBeCloseTo(10 * 1.4, 1); expect(scaled.fileSearch).toBeCloseTo(12 * 1.4, 1); + expect(scaled.settingsSearch).toBeCloseTo(12.5 * 1.4, 1); expect(scaled.navItem).toBeCloseTo(12 * 1.4, 1); } finally { await page.close().catch(() => {}); diff --git a/ui/src/styles/base.css b/ui/src/styles/base.css index 1485c4de3ddf..71252ba11b92 100644 --- a/ui/src/styles/base.css +++ b/ui/src/styles/base.css @@ -638,6 +638,9 @@ body { that `hidden` would let strand the shell off-screen. */ overflow: clip; overscroll-behavior: none; + /* The app supplies its own pressed and selected states; WebKit's tap flash + reads as foreign chrome on top of them. */ + -webkit-tap-highlight-color: transparent; /* iOS WKWebView font boosting inflates rendered text without re-running layout, so labels spill out of fixed-size chrome (welcome chips, badges). Locking text-size-adjust keeps rendered metrics equal to layout metrics. */ @@ -645,6 +648,17 @@ body { text-size-adjust: 100%; } +a, +button, +label, +summary, +input, +select, +textarea, +[role="button"] { + touch-action: manipulation; +} + body { margin: 0; font: 400 14px/1.55 var(--font-body); @@ -659,6 +673,18 @@ body { -moz-osx-font-smoothing: grayscale; } +/* iOS Safari zooms the viewport when a focused text control is under 16px; + important keeps feature-local typography from silently dropping this floor. + Controls that manage their own touch size declare it via + --control-ui-touch-input-size; the floor never caps above 16px. */ +@media (pointer: coarse) { + input, + select, + textarea { + font-size: max(16px, var(--control-ui-touch-input-size, 1em)) !important; + } +} + @media (min-width: 1600px) { body { font-size: 15px; diff --git a/ui/src/styles/chat/layout.css b/ui/src/styles/chat/layout.css index c5a970cd7c9c..6c9f767dfc49 100644 --- a/ui/src/styles/chat/layout.css +++ b/ui/src/styles/chat/layout.css @@ -2450,6 +2450,8 @@ button.chat-reply-preview--message:disabled { } .agent-chat__composer-combobox > :is(textarea, input) { + --control-ui-touch-input-size: var(--control-ui-input-text-size); + width: 100%; min-height: var(--chat-composer-control-height); max-height: calc(7em + 24px); @@ -2484,12 +2486,6 @@ button.chat-reply-preview--message:disabled { text-overflow: ellipsis; } -@media (hover: none) and (pointer: coarse) { - .agent-chat__composer-combobox > :is(textarea, input) { - font-size: var(--control-ui-input-text-size); - } -} - .agent-chat__composer-status-stack { display: flex; flex-wrap: wrap; diff --git a/ui/src/styles/chat/sidebar.css b/ui/src/styles/chat/sidebar.css index 92ad14b082e9..d5ca757dcf1f 100644 --- a/ui/src/styles/chat/sidebar.css +++ b/ui/src/styles/chat/sidebar.css @@ -1507,6 +1507,8 @@ openclaw-session-discussion { } .file-view__search input { + --control-ui-touch-input-size: var(--control-ui-text-sm); + min-width: 0; flex: 1; height: 28px; @@ -1520,12 +1522,6 @@ openclaw-session-discussion { font-size: var(--control-ui-text-sm); } -@media (hover: none) and (pointer: coarse) { - .file-view__search input { - font-size: max(16px, var(--control-ui-text-sm)); - } -} - .file-view__search input:focus-visible { border-color: var(--accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 18%, transparent); diff --git a/ui/src/styles/components.css b/ui/src/styles/components.css index df25d56d4c1d..8954372ba3c8 100644 --- a/ui/src/styles/components.css +++ b/ui/src/styles/components.css @@ -1106,7 +1106,6 @@ openclaw-session-owner-chip { background: transparent; color: var(--muted); cursor: var(--cursor-action); - touch-action: manipulation; } .oc-sensitive-toggle:hover:not(:disabled) { @@ -4408,7 +4407,6 @@ td.data-table-key-col { background-color var(--duration-fast) var(--ease-in-out), border-color var(--duration-fast) var(--ease-in-out), color var(--duration-fast) var(--ease-in-out); - touch-action: manipulation; } .agent-tools-runtime-chip:hover { @@ -4465,7 +4463,6 @@ td.data-table-key-col { transition: background-color var(--duration-fast) var(--ease-in-out), color var(--duration-fast) var(--ease-in-out); - touch-action: manipulation; } .agent-tools-group__summary::before { @@ -4582,7 +4579,6 @@ td.data-table-key-col { transition: background-color var(--duration-fast) var(--ease-in-out), color var(--duration-fast) var(--ease-in-out); - touch-action: manipulation; } .agent-tool-summary::after { diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css index a93668fe5403..6f7e2f537e3c 100644 --- a/ui/src/styles/layout.css +++ b/ui/src/styles/layout.css @@ -391,6 +391,8 @@ html.openclaw-native-web-chrome .shell-chrome-controls { } .settings-sidebar__search-input { + --control-ui-touch-input-size: calc(12.5px * var(--control-ui-text-scale)); + width: 100%; min-width: 0; height: 34px; @@ -423,12 +425,6 @@ html.openclaw-native-web-chrome .shell-chrome-controls { appearance: none; } -@media (hover: none) and (pointer: coarse) { - .settings-sidebar__search-input { - font-size: max(16px, calc(12.5px * var(--control-ui-text-scale))); - } -} - .settings-sidebar__search-clear { position: absolute; inset-inline-end: 5px; @@ -3495,6 +3491,8 @@ wa-dropdown.sidebar-identity-menu::part(menu) { } .sidebar-agent-menu__filter input { + --control-ui-touch-input-size: var(--control-ui-text-sm); + width: 100%; padding: 5px 8px; border-radius: 6px; @@ -3505,12 +3503,6 @@ wa-dropdown.sidebar-identity-menu::part(menu) { font-size: var(--control-ui-text-sm); } -@media (hover: none) and (pointer: coarse) { - .sidebar-agent-menu__filter input { - font-size: max(16px, var(--control-ui-text-sm)); - } -} - .sidebar-agent-menu__empty { padding: 6px 8px; font-size: var(--control-ui-text-sm); diff --git a/ui/src/styles/settings.css b/ui/src/styles/settings.css index 592f8268b20a..46a554fa20f6 100644 --- a/ui/src/styles/settings.css +++ b/ui/src/styles/settings.css @@ -560,6 +560,8 @@ wa-radio-group.settings-segmented::part(radios) { .settings-input, .settings-select { + --control-ui-touch-input-size: var(--control-ui-input-text-size); + width: 100%; min-width: 0; font: inherit; diff --git a/ui/vite.config.ts b/ui/vite.config.ts index 9a96b872c864..48a7b1d73d71 100644 --- a/ui/vite.config.ts +++ b/ui/vite.config.ts @@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url"; import { brotliCompressSync, constants as zlibConstants, gzipSync } from "node:zlib"; import type { Plugin, UserConfig } from "vite"; import { controlUiCodeSplitting } from "./config/control-ui-chunking.ts"; +import { controlUiHoverGuardPlugin } from "./config/control-ui-hover-guard.ts"; import { controlUiLocaleModulesPlugin } from "./config/control-ui-locales.ts"; import { normalizeControlUiBuildInfo } from "./src/build-info-normalizers.ts"; import type { ControlUiBuildInfo } from "./src/build-info.ts"; @@ -431,6 +432,11 @@ export default function controlUiViteConfig(options: { outDir?: string } = {}): "globalThis.OPENCLAW_CONTROL_UI_BUILD_INFO": JSON.stringify(buildInfo), }, publicDir: path.resolve(here, "public"), + css: { + postcss: { + plugins: [controlUiHoverGuardPlugin()], + }, + }, optimizeDeps: { include: [ "ipaddr.js", From 016c5aa772d74ebb47313a31dd236a7d4a622ead Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:48:14 -0700 Subject: [PATCH 062/165] ci: balance Control UI E2E shards by source size (#122527) Co-authored-by: Amp --- docs/ci.md | 1 + test/vitest-ui-e2e-config.test.ts | 56 ++++++++++++++++++++++++++ test/vitest/vitest.ui-e2e.config.ts | 3 ++ test/vitest/vitest.ui-e2e.sequencer.ts | 37 +++++++++++++++++ 4 files changed, 97 insertions(+) create mode 100644 test/vitest-ui-e2e-config.test.ts create mode 100644 test/vitest/vitest.ui-e2e.sequencer.ts diff --git a/docs/ci.md b/docs/ci.md index cdbdbb7280a9..67cd1137dd5e 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -121,6 +121,7 @@ The slowest Node test families are split or balanced so each job stays small wit - Normal CI packs only isolated infra include-pattern shards into deterministic bundles of at most 64 test files, reducing the Node matrix without merging non-isolated command/cron, stateful agents-core, or gateway/server suites. Heavy fixed suites stay on 8 vCPU while the bundled and lower-weight lanes use 4 vCPU. - Pull requests on the canonical repository reuse the changed-test resolver against the synthetic merged-tree diff. Precise changes run one targeted Node job; each selected test file gets its own process so stateful suite isolation remains intact. The planner combines sibling tests with import-graph dependents and falls back to the existing 14-job compact full-suite plan for workspace package, package/lockfile, shared harness, split-config, renamed, or deleted changes, public extension-contract changes, tests with special shard setup, partially resolved or empty targets, oversized path or target plans, and planner errors. Targeted plans always retain the full built-artifact boundary gate because its repository scanners cannot be derived from imports. `main` pushes run the same full compact suite: pending intermediate push events can be coalesced, so the newest surviving run must validate the complete integration tree rather than only its final single-push diff. Manual dispatches and release gates retain the full named per-shard matrix. Compact packing uses fleet timing hints without changing the bounded job count; the high-variance source/security group remains isolated so its tail does not serialize unrelated groups. - The full Node matrix admits the consistently slow serial tooling, auto-reply command shards, and broad core-fast cache writer first. This keeps the 28-job cap while preventing critical-path work and the next run's transform seed from slipping into a later wave. +- The three serial Control UI browser shards greedily pack discovered test files by source byte size. This zero-state duration proxy avoids Vitest's equal-file-count hash clustering, automatically accounts for new and changed files, and preserves the same complete test inventory without adding runners. - Broad browser, QA, media, and miscellaneous plugin tests use their dedicated Vitest configs instead of the shared plugin catch-all. Include-pattern shards record timing entries using the CI shard name, so `.artifacts/vitest-shard-timings.json` can distinguish a whole config from a filtered shard. - Linux Node shard jobs persist Vitest's experimental filesystem module cache through the upstream Actions cache API, which Blacksmith transparently accelerates on its runners. Every CI shard is restore-only and unpacks the protected seed into its own runner-local root; the shard wrapper then gives concurrent Vitest processes separate live subdirectories. Only the non-cancelling daily or explicitly dispatched warmer saves a new immutable archive, so pull requests cannot publish transforms or mint per-PR cache families. The warmer launches each selected shard/config envelope in a fresh child process with concurrency one, preserving its include patterns and environment while reusing the same serial cache leaf. This prevents config-global state from leaking, avoids expanding filtered shards into whole configs, and retains transforms produced by the previous child. A transform-input fingerprint clears incompatible lockfile, package, tsconfig, and Vitest-config generations. The protected writer scans and prunes its restored cache to 75% after it exceeds 2 GiB. Vitest hashes module id, source content, environment, and resolved transform config, so ordinary partial source changes keep unchanged entries warm while changed modules miss safely. Coarse restore prefixes bridge workflow runs; normal Actions cache LRU and inactivity eviction bound old immutable archives. - Trusted Blacksmith Linux Node jobs also bind the pnpm store and `node_modules` from one protected dependency disk per supported Node line. GitHub-hosted jobs, including manual dispatches, fork pull requests, and same-repo retries of both UI E2E jobs, use the Actions cache path instead. Package manifests, install settings, runner platform, and the exact Node patch stay out of the disk key; an exact runtime and install-input fingerprint decides whether a job reuses the tree or reinstalls and refreshes the same disk. Manifests are canonicalized before hashing. The audited direct root hooks retain only pnpm's install lifecycle scripts, so formatting and ordinary test/build script edits keep the warm dependency tree; unaudited lifecycle-hook drift fails closed until its source inputs join the fingerprint contract. Dependency, package-manager, hook-source, and lockfile changes always invalidate the snapshot. A matching fingerprint is necessary but not sufficient: setup also checks the importer archive and manifest checksums, then verifies registry-backed lockfile dependencies retained by postinstall against the package manifests Node resolves from their importers. Missing or stale importer content falls back to a fresh install instead of serving the root hoist. A pull request whose read-only snapshot is unusable detaches the workspace bind and installs into runner-local storage, avoiding slow writes to a clone it cannot publish. Sticky cold installs disable pnpm's inner fetch retries and make up to three bounded full-install attempts from the progressively warmed store; a timeout remains a failure. After a content-validated restore or frozen-lockfile install, setup disables pnpm's redundant pre-run dependency check: the repository intentionally prunes plugin-local `node_modules`, which pnpm otherwise treats as stale and repairs through unsafe concurrent implicit installs during shard fanout. Canonical main preflight is the sole writer and measures the store on every refresh, running `pnpm store prune` only after retired package versions push it above 8 GiB. Validated warm restores no longer publish no-op snapshots: the writer uses StickyDisk's allocation-change mode, records its mount-time allocation baseline, and only a successful dependency capture creates a runner-local rebuild signal. After store pruning, preflight compares the final whole-disk allocation to that baseline and, when needed, allocates a bounded sentinel until the absolute delta has a verified 64 KiB margin over StickyDisk's 4 KiB threshold. Blacksmith snapshot publication is asynchronous even after a writer job completes, so the first run after a fresh key or fingerprint can remain cold; later content-validated exact-marker restores are the rollout proof. Required Blacksmith CI jobs and first-attempt same-repo pull requests get disposable clones, so dependency changes do not create new disks, competing snapshots, or a cache lock that can cancel builds. diff --git a/test/vitest-ui-e2e-config.test.ts b/test/vitest-ui-e2e-config.test.ts new file mode 100644 index 000000000000..b95705316a41 --- /dev/null +++ b/test/vitest-ui-e2e-config.test.ts @@ -0,0 +1,56 @@ +// Vitest UI E2E config tests protect complete, size-balanced browser sharding. +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import type { TestSpecification } from "vitest/node"; +import uiE2eConfig from "./vitest/vitest.ui-e2e.config.ts"; +import { UiE2eSequencer } from "./vitest/vitest.ui-e2e.sequencer.ts"; + +const tempDirs: string[] = []; + +afterEach(() => { + for (const dir of tempDirs.splice(0)) { + fs.rmSync(dir, { force: true, recursive: true }); + } +}); + +function requireTestConfig(config: unknown): { + sequence?: { sequencer?: unknown }; +} { + if (!config || typeof config !== "object" || !("test" in config) || !config.test) { + throw new Error("expected UI E2E Vitest test config"); + } + return config.test as { sequence?: { sequencer?: unknown } }; +} + +async function shardFiles(files: TestSpecification[], index: number, count: number) { + const sequencer = new UiE2eSequencer({ config: { shard: { count, index } } } as never); + return sequencer.shard(files); +} + +describe("Control UI E2E Vitest sharding", () => { + it("uses the source-size weighted sequencer", () => { + expect(requireTestConfig(uiE2eConfig).sequence?.sequencer).toBe(UiE2eSequencer); + }); + + it("covers every file once while balancing source bytes", async () => { + const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-ui-e2e-shards-")); + tempDirs.push(tempDir); + const files = [600, 500, 400, 300, 200, 100].map((bytes, index) => { + const moduleId = path.join(tempDir, `suite-${index}.e2e.test.ts`); + fs.writeFileSync(moduleId, "x".repeat(bytes)); + return { moduleId } as TestSpecification; + }); + + const shards = await Promise.all([1, 2, 3].map((index) => shardFiles(files, index, 3))); + const assignedFiles = shards.flat().map((file) => file.moduleId); + const assignedBytes = shards.map((shard) => + shard.reduce((total, file) => total + fs.statSync(file.moduleId).size, 0), + ); + + expect(assignedFiles.toSorted()).toEqual(files.map((file) => file.moduleId).toSorted()); + expect(new Set(assignedFiles).size).toBe(files.length); + expect(assignedBytes).toEqual([700, 700, 700]); + }); +}); diff --git a/test/vitest/vitest.ui-e2e.config.ts b/test/vitest/vitest.ui-e2e.config.ts index 730d8147930d..e1713e019e5e 100644 --- a/test/vitest/vitest.ui-e2e.config.ts +++ b/test/vitest/vitest.ui-e2e.config.ts @@ -2,6 +2,7 @@ import { defineConfig } from "vitest/config"; import { loadPatternListFromEnv, narrowIncludePatternsForCli } from "./vitest.pattern-file.ts"; import { sharedVitestConfig } from "./vitest.shared.config.ts"; +import { UiE2eSequencer } from "./vitest.ui-e2e.sequencer.ts"; const uiE2eIncludePatterns = ["ui/src/**/*.e2e.test.ts"]; const uiE2eRealGatewayTestFiles = [ @@ -15,6 +16,7 @@ function createUiE2eVitestConfig( ) { const base = sharedVitestConfig as Record; const baseTest = sharedVitestConfig.test ?? {}; + const baseSequence = (baseTest as { sequence?: object }).sequence; const exclude = [ ...(baseTest.exclude ?? []).filter((pattern) => pattern !== "**/*.e2e.test.ts"), ...(env.OPENCLAW_UI_E2E_SKIP_REAL_GATEWAY === "1" ? uiE2eRealGatewayTestFiles : []), @@ -44,6 +46,7 @@ function createUiE2eVitestConfig( name: "ui-e2e", pool: "forks", runner: undefined, + sequence: { ...baseSequence, sequencer: UiE2eSequencer }, setupFiles: ["test/vitest/vitest.ui-e2e.setup.ts"], }, }); diff --git a/test/vitest/vitest.ui-e2e.sequencer.ts b/test/vitest/vitest.ui-e2e.sequencer.ts new file mode 100644 index 000000000000..2cad4b71291d --- /dev/null +++ b/test/vitest/vitest.ui-e2e.sequencer.ts @@ -0,0 +1,37 @@ +// Source-size weighted sharding keeps serial Control UI E2E runners from +// clustering the largest browser suites behind Vitest's equal-file-count hash. +import { statSync } from "node:fs"; +import { BaseSequencer, type TestSpecification } from "vitest/node"; + +type ShardBucket = { + bytes: number; + files: TestSpecification[]; +}; + +export class UiE2eSequencer extends BaseSequencer { + override async shard(files: TestSpecification[]): Promise { + // Vitest invokes shard() only when config.shard is present. File size is a + // zero-state duration proxy, so new and changed tests rebalance automatically. + const { count, index } = this.ctx.config.shard!; + const buckets: ShardBucket[] = Array.from({ length: count }, () => ({ + bytes: 0, + files: [], + })); + const weightedFiles = files + .map((file) => ({ bytes: statSync(file.moduleId).size, file })) + .sort( + (left, right) => + right.bytes - left.bytes || left.file.moduleId.localeCompare(right.file.moduleId), + ); + + for (const weightedFile of weightedFiles) { + const bucket = buckets.reduce((lightest, candidate) => + candidate.bytes < lightest.bytes ? candidate : lightest, + ); + bucket.bytes += weightedFile.bytes; + bucket.files.push(weightedFile.file); + } + + return buckets[index - 1]!.files; + } +} From 5a643e35431061f7bcbfcdb338d33441ec45bd92 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 00:49:29 -0700 Subject: [PATCH 063/165] fix(plugins): keep packed entries consistent through package lifecycle (#121174) * fix(plugins): own packed entry lifecycles by package Persist package ownership per runtime child, route lifecycle actions through one closed resolver, reconcile removed child policy during updates, and retain rollback generations until durable config/index commit. * fix(plugins): break uninstall policy import cycle * test(plugins): model package ownership in lifecycle fixtures --- docs/cli/plugins.md | 8 +- docs/plugins/manage-plugins.md | 28 +- scripts/e2e/lib/fixtures/plugins.mjs | 33 ++ src/cli/plugins-cli-test-helpers.ts | 31 +- src/cli/plugins-cli.install.test.ts | 32 +- src/cli/plugins-cli.uninstall.test.ts | 89 +++-- src/cli/plugins-cli.update.test.ts | 146 +++++-- src/cli/plugins-uninstall-command.ts | 98 ++++- src/cli/plugins-update-command.ts | 370 ++++++++++++------ src/cli/plugins-update-selection.test.ts | 59 +++ src/cli/plugins-update-selection.ts | 27 +- .../shared/plugin-registry-migration.test.ts | 24 +- src/infra/install-package-dir.test.ts | 38 +- src/infra/install-package-dir.ts | 84 +++- src/plugins/candidate-install-owner.ts | 56 +++ src/plugins/clawhub.ts | 47 +-- src/plugins/discovery.test.ts | 150 ++++++- src/plugins/discovery.ts | 105 ++++- src/plugins/git-install.ts | 34 +- src/plugins/install-managed-npm.ts | 76 +++- src/plugins/install-npm.ts | 57 +-- src/plugins/install-package.ts | 147 +++---- src/plugins/install-persistence.test.ts | 144 ++++--- src/plugins/install-persistence.ts | 196 +++++++--- src/plugins/install-record-commit.ts | 22 +- src/plugins/install-shared.ts | 39 +- src/plugins/install-transaction.ts | 112 ++++++ .../installed-plugin-index-install-owner.ts | 43 ++ .../installed-plugin-index-invalidation.ts | 8 + .../installed-plugin-index-record-builder.ts | 31 +- src/plugins/installed-plugin-index-store.ts | 36 +- .../installed-plugin-package-ownership.ts | 159 ++++++++ src/plugins/loader-provenance.ts | 21 +- src/plugins/loader-runtime-load.ts | 31 +- src/plugins/loader-shared.test.ts | 27 +- src/plugins/loader-shared.ts | 37 +- src/plugins/management-service.test.ts | 21 +- src/plugins/management-service.ts | 157 ++++++-- ...gement-service.uninstall-ownership.test.ts | 194 ++++++++- src/plugins/manifest-install-owner.ts | 33 ++ .../manifest-registry-installed.test.ts | 195 ++++++++- src/plugins/manifest-registry-installed.ts | 52 ++- src/plugins/manifest-registry.test.ts | 117 ++++-- src/plugins/manifest-registry.ts | 37 +- src/plugins/marketplace.ts | 53 +-- src/plugins/plugin-package-update.test.ts | 165 ++++++++ src/plugins/plugin-package-update.ts | 128 ++++++ src/plugins/plugin-registry-snapshot.test.ts | 32 ++ src/plugins/plugin-registry-snapshot.ts | 10 +- src/plugins/uninstall-config.ts | 193 ++------- src/plugins/uninstall-package-config.ts | 227 +++++++++++ src/plugins/uninstall-package-plan.ts | 48 +++ src/plugins/uninstall.test.ts | 164 ++++++-- src/plugins/uninstall.ts | 62 +-- src/plugins/update-attempt.ts | 203 +++++----- src/plugins/update-installed.ts | 101 +++-- src/plugins/update-summary.ts | 113 ++++++ .../plugins/plugin-lifecycle-probe-runtime.ts | 217 +++++++++- ui/src/i18n/locales/en.ts | 2 +- ui/src/pages/plugins/view.test.ts | 2 +- 60 files changed, 4069 insertions(+), 1102 deletions(-) create mode 100644 src/plugins/candidate-install-owner.ts create mode 100644 src/plugins/install-transaction.ts create mode 100644 src/plugins/installed-plugin-index-install-owner.ts create mode 100644 src/plugins/installed-plugin-package-ownership.ts create mode 100644 src/plugins/manifest-install-owner.ts create mode 100644 src/plugins/plugin-package-update.test.ts create mode 100644 src/plugins/plugin-package-update.ts create mode 100644 src/plugins/uninstall-package-config.ts create mode 100644 src/plugins/uninstall-package-plan.ts create mode 100644 src/plugins/update-summary.ts diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index b8178f9e8bda..aa7c914ac04f 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -421,9 +421,11 @@ openclaw plugins uninstall --keep-files openclaw plugins uninstall --force ``` -`uninstall` removes plugin records from `plugins.entries`, the persisted plugin index, plugin allow/deny list entries, and any `plugins.load.paths` entry that exactly resolves to the recorded install path. Linked path installs also remove an exact entry for their recorded source path. Parent directories, child paths, prefix matches, and unrelated load paths are preserved. Unless `--keep-files` is set, uninstall also removes the tracked managed install directory, but only when it resolves inside OpenClaw's plugin extensions root. If the plugin currently owns the `memory` or `contextEngine` slot, that slot resets to its default (`memory-core` for memory, `legacy` for context engine). +`uninstall` removes plugin records from `plugins.entries`, the persisted plugin index, plugin allow/deny list entries, and any `plugins.load.paths` entry that exactly resolves to the recorded install path. For a package with multiple child entries, any child id resolves to the package owner; uninstall removes every sibling's policy and slot/channel references, the one package install record, and the managed directory once. Linked path installs also remove an exact entry for their recorded source path. Parent directories, child paths, prefix matches, and unrelated load paths are preserved. Unless `--keep-files` is set, uninstall also removes the tracked managed install directory, but only when it resolves inside OpenClaw's plugin extensions root. If the plugin currently owns the `memory` or `contextEngine` slot, that slot resets to its default (`memory-core` for memory, `legacy` for context engine). -`uninstall` prints a preview of what will be removed, then prompts `Uninstall plugin ""?` before making changes. Pass `--force` to skip the confirmation prompt (useful for scripts and non-interactive runs); without it, uninstall requires an interactive TTY. `--dry-run` prints the same preview and exits without prompting or changing anything. +`uninstall` prints a preview of what will be removed. Multi-entry packages name the package owner and every affected child before prompting. Pass `--force` to skip the confirmation prompt (useful for scripts and non-interactive runs); without it, uninstall requires an interactive TTY. `--dry-run` prints the same preview and exits without prompting or changing anything. + +If OpenClaw cannot prove exactly one package owner and a complete child list, lifecycle mutations fail closed without changing package files, config, or the installed index. Run `openclaw plugins registry --refresh`, inspect `openclaw plugins doctor`, and use `openclaw doctor --fix` for repairable legacy index state. If ownership is still ambiguous, reinstall the package before retrying update or uninstall. `--keep-config` is supported as a deprecated alias for `--keep-files`. @@ -445,7 +447,7 @@ Updates apply to tracked plugin installs in the managed plugin index and tracked - When you pass a plugin id, OpenClaw reuses the recorded install spec for that plugin. That means previously stored dist-tags such as `@beta` and exact pinned versions continue to be used on later `update ` runs. + When you pass a plugin id, OpenClaw reuses the recorded install spec for that plugin. For a multi-entry package, a child id resolves to its package owner and updates every sibling together. If the new package version removes or renames children, OpenClaw removes the retired children's entries, allow/deny policy, exact child load paths, channel config, and memory/context slot selections while preserving retained/new children and unrelated plugins. Previously stored dist-tags such as `@beta` and exact pinned versions continue to be used on later `update ` runs. The narrow exception is a trusted official package completing a catalog-declared plugin id replacement. That update starts from the catalog package selector so the renamed manifest can replace the legacy id. diff --git a/docs/plugins/manage-plugins.md b/docs/plugins/manage-plugins.md index 67f2b02e3e1f..2856957d7a42 100644 --- a/docs/plugins/manage-plugins.md +++ b/docs/plugins/manage-plugins.md @@ -143,6 +143,12 @@ OpenClaw records the install but leaves the plugin disabled. Configure `plugins.entries..config`, then run `openclaw plugins enable `. If an existing config entry is present but invalid, install fails without rewriting it. +A plugin package can expose multiple child entries. Installation tracks that +package once, enables each ready child entry, and preserves any child that you +explicitly disabled. Runtime policy remains child-addressable through +`plugins.entries.`, allow/deny lists, channel config, exact child load +paths, and the `memory` and `contextEngine` slots. + ## Restart and inspect A running managed Gateway with config reload enabled restarts automatically @@ -171,7 +177,17 @@ openclaw plugins update --dry-run Passing a plugin id reuses its tracked install spec: stored dist-tags (`@beta`) and exact pinned versions carry over to later `update ` -runs. +runs. For a multi-entry package, any child id resolves to the one tracked +package install, so all siblings update together. Removed or renamed children +have their stale entries, allow/deny policy, exact load paths, channel config, +and memory/context slot selections reconciled before the new package/index +state commits; retained/new children and unrelated plugins are preserved. + +If OpenClaw cannot prove exactly one package owner and a complete child list, +update and uninstall fail closed without changing package files, config, or the +installed index. Run `openclaw plugins registry --refresh`, inspect +`openclaw plugins doctor`, and use `openclaw doctor --fix` for repairable legacy +index state. If the ambiguity remains, reinstall the package before retrying. `openclaw plugins update --all` is the bulk maintenance path. It still respects ordinary tracked install specs, but trusted official OpenClaw @@ -204,10 +220,12 @@ openclaw plugins uninstall openclaw plugins uninstall --keep-files ``` -Uninstall removes the plugin's config entry, persisted plugin index record, -allow/deny list entries, and linked `plugins.load.paths` entries when -applicable. The managed install directory is removed unless you pass -`--keep-files`. A running managed Gateway restarts automatically when the +Uninstall removes the package's persisted install record and every owned child +entry from plugin config, allow/deny lists, memory/context slots, exact linked +`plugins.load.paths`, and channel config entries when applicable. You may address a multi-entry +package by any child id; the preview names the package owner and all siblings +that will be removed. The managed install directory is removed once unless you +pass `--keep-files`. A running managed Gateway restarts automatically when the uninstall changes plugin source. In Nix mode (`OPENCLAW_NIX_MODE=1`), plugin install, update, uninstall, diff --git a/scripts/e2e/lib/fixtures/plugins.mjs b/scripts/e2e/lib/fixtures/plugins.mjs index 7f212712455e..378ba04a1a1d 100644 --- a/scripts/e2e/lib/fixtures/plugins.mjs +++ b/scripts/e2e/lib/fixtures/plugins.mjs @@ -47,6 +47,38 @@ function writePlugin([dir, id, version, method, name]) { writePluginManifest(path.join(dir, "openclaw.plugin.json"), id); } +function writePluginPack([dir, id, version, entryList]) { + for (const [value, label] of [ + [dir, "dir"], + [id, "id"], + [version, "version"], + ]) { + requireArg(value, label); + } + const entries = entryList + ? entryList + .split(",") + .map((entry) => entry.trim()) + .filter(Boolean) + : ["one", "two"]; + if (entries.length === 0) { + throw new Error("plugin-pack entries must not be empty"); + } + writeJson(path.join(dir, "package.json"), { + name: `@openclaw/${id}`, + version, + openclaw: { extensions: entries.map((entry) => `./${entry}.js`) }, + }); + for (const entry of entries) { + const childId = `${id}/${entry}`; + write( + path.join(dir, `${entry}.js`), + `module.exports = { id: ${JSON.stringify(childId)}, name: ${JSON.stringify(childId)}, register(api) { api.registerGatewayMethod(${JSON.stringify(`${id}.${entry}`)}, async () => ({ version: ${JSON.stringify(version)} })); }, };\n`, + ); + } + writePluginManifest(path.join(dir, "openclaw.plugin.json"), id); +} + function writePluginWithVendoredDependency([dir, id, version, method, name]) { writePlugin([dir, id, version, method, name]); const packageJsonPath = path.join(dir, "package.json"); @@ -162,6 +194,7 @@ function writePluginMarketplace(args) { export const pluginCommands = { "plugin-demo": writePluginDemo, plugin: writePlugin, + "plugin-pack": writePluginPack, "plugin-vendored-dep": writePluginWithVendoredDependency, "plugin-cli": writePluginWithCli, "plugin-cli-registry-dep": writePluginWithCliRegistryDependency, diff --git a/src/cli/plugins-cli-test-helpers.ts b/src/cli/plugins-cli-test-helpers.ts index 4831fd2f8358..c972256717c3 100644 --- a/src/cli/plugins-cli-test-helpers.ts +++ b/src/cli/plugins-cli-test-helpers.ts @@ -7,6 +7,7 @@ import type { HookInstallRecord } from "../config/types.hooks.js"; import type { OpenClawConfig } from "../config/types.openclaw.js"; import type { PluginInstallRecord } from "../config/types.plugins.js"; import type { InstalledPluginIndex } from "../plugins/installed-plugin-index.js"; +import { recordPluginManifestInstallOwner } from "../plugins/manifest-install-owner.js"; import type { CliMockOutputRuntime } from "./test-runtime-capture.js"; type UnknownMock = Mock<(...args: unknown[]) => unknown>; @@ -69,6 +70,7 @@ function clonePluginInstallRecords(records: PluginInstallRecordMap): PluginInsta export function createTestInstalledPluginIndex(params: { policyHash: string; installRecords: PluginInstallRecordMap; + plugins?: InstalledPluginIndex["plugins"]; }): InstalledPluginIndex { return { version: 1, @@ -79,7 +81,7 @@ export function createTestInstalledPluginIndex(params: { generatedAtMs: 0, refreshReason: "source-changed", installRecords: clonePluginInstallRecords(params.installRecords), - plugins: [], + plugins: params.plugins ?? [], diagnostics: [], }; } @@ -955,9 +957,30 @@ export function resetPluginsCliTestState() { return true; }, ); - loadPluginManifestRegistryMock.mockReturnValue({ - plugins: [], - diagnostics: [], + loadPluginManifestRegistryMock.mockImplementation((input: unknown) => { + const installRecords = + (input as { installRecords?: PluginInstallRecordMap } | undefined)?.installRecords ?? {}; + return { + plugins: Object.entries(installRecords).map(([pluginId, record]) => { + const rootDir = record.installPath ?? record.sourcePath ?? `/tmp/${pluginId}`; + return recordPluginManifestInstallOwner( + { + id: pluginId, + channels: [], + providers: [], + cliBackends: [], + skills: [], + hooks: [], + origin: "global", + rootDir, + source: `${rootDir}/index.js`, + manifestPath: `${rootDir}/openclaw.plugin.json`, + }, + pluginId, + ); + }), + diagnostics: [], + }; }); const defaultPluginReport = { plugins: [], diff --git a/src/cli/plugins-cli.install.test.ts b/src/cli/plugins-cli.install.test.ts index 9714dc518937..63a667aa2ebc 100644 --- a/src/cli/plugins-cli.install.test.ts +++ b/src/cli/plugins-cli.install.test.ts @@ -6,6 +6,7 @@ import { installedPluginRoot } from "openclaw/plugin-sdk/test-fixtures"; import { afterEach, beforeEach, describe, expect, it } from "vitest"; import type { OpenClawConfig } from "../config/config.js"; import { hashConfigIncludeRaw } from "../config/includes.js"; +import { recordPluginManifestInstallOwner } from "../plugins/manifest-install-owner.js"; import { listOfficialExternalPluginCatalogEntries, resolveOfficialExternalPluginId, @@ -1268,7 +1269,7 @@ describe("plugins cli install", () => { marketplaceSource: "local/repo", marketplacePlugin: "alpha", }); - enablePluginInConfigMock.mockReturnValue({ config: enabledCfg }); + enablePluginInConfigMock.mockReturnValue({ config: enabledCfg, enabled: true }); buildPluginSnapshotReportMock.mockReturnValue({ plugins: [{ id: "alpha", kind: "provider" }], diagnostics: [], @@ -1276,19 +1277,22 @@ describe("plugins cli install", () => { const alphaRoot = cliInstallPath("alpha"); loadPluginManifestRegistryMock.mockReturnValue({ plugins: [ - { - id: "alpha", - kind: "memory", - origin: "global", - channels: [], - providers: [], - cliBackends: [], - skills: [], - hooks: [], - rootDir: alphaRoot, - source: `${alphaRoot}/index.js`, - manifestPath: `${alphaRoot}/openclaw.plugin.json`, - }, + recordPluginManifestInstallOwner( + { + id: "alpha", + kind: "memory", + origin: "global", + channels: [], + providers: [], + cliBackends: [], + skills: [], + hooks: [], + rootDir: alphaRoot, + source: `${alphaRoot}/index.js`, + manifestPath: `${alphaRoot}/openclaw.plugin.json`, + }, + "alpha", + ), ], diagnostics: [], }); diff --git a/src/cli/plugins-cli.uninstall.test.ts b/src/cli/plugins-cli.uninstall.test.ts index 95af6dc1d22f..5a40cb1a7a7a 100644 --- a/src/cli/plugins-cli.uninstall.test.ts +++ b/src/cli/plugins-cli.uninstall.test.ts @@ -150,6 +150,9 @@ describe("plugins cli uninstall", () => { plugins: [{ id: "alpha", name: "alpha" }], diagnostics: [], }); + setInstalledPluginIndexInstallRecords({ + alpha: { source: "path", sourcePath: ALPHA_INSTALL_PATH, installPath: ALPHA_INSTALL_PATH }, + }); primeUninstallPlan({} as OpenClawConfig, { actions: { contextEngineSlot: true } }); await runPluginsCommand(["plugins", "uninstall", "alpha", "--dry-run"]); @@ -564,42 +567,58 @@ describe("plugins cli uninstall", () => { expect(refreshPluginRegistryMock).not.toHaveBeenCalled(); }); - it("cleans stale policy refs even when plugin is absent from the current registry", async () => { + it("rejects stale child-keyed records that claim one package path", async () => { + const sharedPath = "/tmp/openclaw-ambiguous-uninstall-pack"; + const installRecords = { + "pack/one": { + source: "npm" as const, + spec: "@acme/pack", + installPath: sharedPath, + }, + "pack/two": { + source: "npm" as const, + spec: "@acme/pack", + installPath: sharedPath, + }, + }; + const config = {} as OpenClawConfig; + pluginCliConfigMock.mockReturnValue(config); + setInstalledPluginIndexInstallRecords(installRecords); + buildPluginSnapshotReportMock.mockReturnValue({ + plugins: [{ id: "pack/one", name: "pack/one" }], + diagnostics: [], + }); + + await expect( + runPluginsCommand(["plugins", "uninstall", "pack/one", "--force"]), + ).rejects.toThrow("__exit__:1"); + + expect(runtimeErrors.at(-1)).toContain('Plugin "pack/one"'); + expect(planPluginUninstallMock).not.toHaveBeenCalled(); + expect(configWriteMock).not.toHaveBeenCalled(); + }); + + it("fails closed for stale policy refs without authoritative installed children", async () => { const baseConfig = { plugins: { allow: ["alpha", "beta"], deny: ["alpha"], }, } as OpenClawConfig; - const nextConfig = { - plugins: { - allow: ["beta"], - }, - } as OpenClawConfig; - pluginCliConfigMock.mockReturnValue(baseConfig); buildPluginSnapshotReportMock.mockReturnValue({ plugins: [], diagnostics: [], }); - primeUninstallPlan(nextConfig, { - actions: { - entry: false, - install: false, - allowlist: true, - denylist: true, - channelConfig: false, - }, - }); - await runPluginsCommand(["plugins", "uninstall", "alpha", "--force"]); - - expectLatestUninstallPlanParams({ pluginId: "alpha", deleteFiles: true }); - expect(configWriteMock).toHaveBeenCalledWith(nextConfig); - expect(pluginsCliRuntimeLogs.at(-2)).toContain('Uninstalled plugin "alpha"'); + await expect(runPluginsCommand(["plugins", "uninstall", "alpha", "--force"])).rejects.toThrow( + "__exit__:1", + ); + expect(planPluginUninstallMock).not.toHaveBeenCalled(); + expect(configWriteMock).not.toHaveBeenCalled(); }); - it("uninstalls stale enabled entries when plugin is absent from the current registry", async () => { + it("fails closed for stale enabled entries without authoritative installed children", async () => { const baseConfig = { plugins: { entries: { @@ -607,28 +626,18 @@ describe("plugins cli uninstall", () => { }, }, } as OpenClawConfig; - const nextConfig = {} as OpenClawConfig; - pluginCliConfigMock.mockReturnValue(baseConfig); buildPluginSnapshotReportMock.mockReturnValue({ plugins: [], diagnostics: [], }); - primeUninstallPlan(nextConfig, { - actions: { install: false, channelConfig: false }, - }); - await runPluginsCommand(["plugins", "uninstall", "alpha", "--force"]); - - expectLatestUninstallPlanParams({ pluginId: "alpha", deleteFiles: true }); - expect(configWriteMock).toHaveBeenCalledWith(nextConfig); - expect(refreshPluginRegistryMock).toHaveBeenCalledWith({ - config: nextConfig, - installRecords: {}, - reason: "source-changed", - }); - expect(runtimeErrors).not.toContain("Plugin not found: alpha"); - expect(pluginsCliRuntimeLogs.at(-2)).toContain('Uninstalled plugin "alpha"'); + await expect(runPluginsCommand(["plugins", "uninstall", "alpha", "--force"])).rejects.toThrow( + "__exit__:1", + ); + expect(planPluginUninstallMock).not.toHaveBeenCalled(); + expect(configWriteMock).not.toHaveBeenCalled(); + expect(refreshPluginRegistryMock).not.toHaveBeenCalled(); }); it.each([ @@ -782,7 +791,7 @@ describe("plugins cli uninstall", () => { "__exit__:1", ); - expect(runtimeErrors.at(-1)).toContain("is not managed by plugins config/install records"); - expect(planPluginUninstallMock).toHaveBeenCalledTimes(1); + expect(runtimeErrors.at(-1)).toContain("is not associated with a tracked package install"); + expect(planPluginUninstallMock).not.toHaveBeenCalled(); }); }); diff --git a/src/cli/plugins-cli.update.test.ts b/src/cli/plugins-cli.update.test.ts index c51587a2a97d..dbf0ee9a0689 100644 --- a/src/cli/plugins-cli.update.test.ts +++ b/src/cli/plugins-cli.update.test.ts @@ -6,6 +6,12 @@ import type { OpenClawConfig } from "../config/config.js"; import type { ClawHubTrustErrorCode } from "../infra/clawhub-install-trust.js"; import { resolveRegistryUpdateChannel } from "../infra/update-channels.js"; import { CLAWHUB_INSTALL_ERROR_CODE } from "../plugins/clawhub-error-codes.js"; +import { + attachPluginInstallOwnerMigrations, + resolvePluginInstallTransactionSink, + type PluginInstallTransaction, +} from "../plugins/install-transaction.js"; +import { recordInstalledPluginIndexInstallOwner } from "../plugins/installed-plugin-index-install-owner.js"; import { VERSION } from "../version.js"; import { createTestInstalledPluginIndex, @@ -168,8 +174,20 @@ function primePluginUpdate( config: OpenClawConfig, outcomes: Awaited>["outcomes"] = [], changed = false, + transactions?: PluginInstallTransaction[], + installOwnerMigrations?: Readonly>, ): void { - updateNpmInstalledPluginsMock.mockResolvedValue({ config, changed, outcomes }); + updateNpmInstalledPluginsMock.mockImplementation(async (params: unknown) => { + resolvePluginInstallTransactionSink(params as object)?.push(...(transactions ?? [])); + const result = { + config, + changed, + outcomes, + }; + return installOwnerMigrations + ? attachPluginInstallOwnerMigrations(result, installOwnerMigrations) + : result; + }); } function primeBravePluginRecordUpdate(config: OpenClawConfig) { @@ -379,6 +397,33 @@ describe("plugins cli update", () => { expect(configWriteMock).not.toHaveBeenCalled(); }); + it.each([ + { label: "a stale child-keyed owner", args: ["pack/one"] }, + { label: "update all", args: ["--all"] }, + ])("rejects ambiguous package paths for $label", async ({ args }) => { + const sharedPath = "/tmp/openclaw-ambiguous-update-pack"; + const installRecords = { + "pack/one": { + source: "npm" as const, + spec: "@acme/pack", + installPath: sharedPath, + }, + "pack/two": { + source: "npm" as const, + spec: "@acme/pack", + installPath: sharedPath, + }, + }; + const config = {} as OpenClawConfig; + primeUpdateConfigSnapshot({ config }); + setInstalledPluginIndexInstallRecords(installRecords); + + await expect(runPluginsCommand(["plugins", "update", ...args])).rejects.toThrow("__exit__:1"); + + expect(updateNpmInstalledPluginsMock).not.toHaveBeenCalled(); + expect(configWriteMock).not.toHaveBeenCalled(); + }); + it("updates tracked hook packs through plugins update", async () => { const cfg = {} as OpenClawConfig; const nextConfig = cfg; @@ -592,6 +637,8 @@ describe("plugins cli update", () => { }, ], true, + undefined, + { "voice-call": "@openclaw/voice-call" }, ); await runPluginsCommand(["plugins", "update", "--all"]); @@ -603,13 +650,11 @@ describe("plugins cli update", () => { expect(configWriteMock).not.toHaveBeenCalled(); }); - it("allows scoped non-npm updates beside include-owned plugin config", async () => { + it("blocks child load-path cleanup beside include-owned plugin config", async () => { const pluginId = "@acme/demo"; const cfg = { plugins: { - entries: { - [pluginId]: { enabled: true }, - }, + load: { paths: ["/tmp/demo/index.js"] }, }, } as OpenClawConfig; const pluginRecords = { @@ -634,11 +679,11 @@ describe("plugins cli update", () => { true, ); - await runPluginsCommand(["plugins", "update", pluginId]); + await expect(runPluginsCommand(["plugins", "update", pluginId])).rejects.toThrow("__exit__:1"); - expect(runtimeErrors).toEqual([]); - expect(updateNpmInstalledPluginsMock).toHaveBeenCalledOnce(); - expectInstallRecordsWrittenWithLease(pluginRecords, cfg); + expect(runtimeErrors.at(-1)).toContain("external or unresolved top-level $include"); + expect(updateNpmInstalledPluginsMock).not.toHaveBeenCalled(); + expect(writePersistedInstalledPluginIndexInstallRecordsWithLeaseMock).not.toHaveBeenCalled(); expect(configWriteMock).not.toHaveBeenCalled(); }); @@ -793,9 +838,33 @@ describe("plugins cli update", () => { .mockResolvedValueOnce(initialSnapshot) .mockResolvedValueOnce(changedSnapshot); const { previousRecords, nextRecords } = primeBravePluginRecordUpdate(cfg); + const rollback = vi.fn(async () => undefined); + const commit = vi.fn(async () => undefined); + primePluginUpdate( + { ...cfg, plugins: { ...cfg.plugins, installs: nextRecords } }, + [{ pluginId: "brave", status: "updated", message: "Updated brave." }], + true, + [{ rollback, commit }], + ); const previousPersistedIndex = createTestInstalledPluginIndex({ policyHash: "previous-policy", installRecords: previousRecords, + plugins: [ + recordInstalledPluginIndexInstallOwner( + { + pluginId: "brave", + manifestPath: "/tmp/brave-beta/openclaw.plugin.json", + manifestHash: "brave-v1", + source: "/tmp/brave-beta/index.js", + rootDir: "/tmp/brave-beta", + origin: "global", + enabled: true, + startup: { sidecar: false, memory: false, agentHarnesses: [] }, + compat: [], + }, + "brave", + ), + ], }); readPersistedInstalledPluginIndexMock.mockResolvedValue(previousPersistedIndex); @@ -816,18 +885,14 @@ describe("plugins cli update", () => { expect(replaceConfigFileMock).not.toHaveBeenCalled(); expect(refreshPluginRegistryMock).not.toHaveBeenCalled(); expect(notifyGatewayPluginMetadataChangedMock).not.toHaveBeenCalled(); + expect(rollback).toHaveBeenCalledTimes(1); + expect(commit).not.toHaveBeenCalled(); }); it("rolls back persisted install records when included config changes during a records-only update", async () => { const includePath = "/tmp/plugins.json5"; const includeTarget = "/tmp/plugins.json5"; - const cfg = { - plugins: { - entries: { - brave: { enabled: true }, - }, - }, - } as OpenClawConfig; + const cfg = { plugins: {} } as OpenClawConfig; const initialSnapshot = primeUpdateConfigSnapshot({ config: cfg, parsed: { @@ -854,14 +919,34 @@ describe("plugins cli update", () => { readConfigFileSnapshotForWriteMock .mockResolvedValueOnce(initialSnapshot) .mockResolvedValueOnce(changedSnapshot); - const { previousRecords, nextRecords } = primeBravePluginRecordUpdate(cfg); + const pluginId = "@openclaw/brave-plugin"; + const previousRecords = { + [pluginId]: { + source: "npm" as const, + spec: `${pluginId}@1.0.0`, + installPath: "/tmp/brave-beta", + }, + }; + const nextRecords = { + [pluginId]: { + ...previousRecords[pluginId], + spec: `${pluginId}@2.0.0`, + installPath: "/tmp/brave-stable", + }, + }; + setInstalledPluginIndexInstallRecords(previousRecords); + primePluginUpdate( + { ...cfg, plugins: { installs: nextRecords } }, + [{ pluginId, status: "updated", message: `Updated ${pluginId}.` }], + true, + ); const previousPersistedIndex = createTestInstalledPluginIndex({ policyHash: "previous-policy", installRecords: previousRecords, }); readPersistedInstalledPluginIndexMock.mockResolvedValue(previousPersistedIndex); - await expect(runPluginsCommand(["plugins", "update", "brave"])).rejects.toThrow( + await expect(runPluginsCommand(["plugins", "update", pluginId])).rejects.toThrow( "included config changed since last load", ); @@ -1411,7 +1496,7 @@ describe("plugins cli update", () => { expect(updateParams.onClawHubRisk).toBeUndefined(); }); - it("writes updated config when updater reports changes", async () => { + it("keeps durable state when transaction cleanup fails after the write", async () => { const cfg = { plugins: { installs: { @@ -1450,10 +1535,19 @@ describe("plugins cli update", () => { }, }); setInstalledPluginIndexInstallRecords(cfg.plugins?.installs ?? {}); + const rollback = vi.fn(async () => undefined); + const failedCommit = vi.fn(async () => { + throw new Error("cleanup failed"); + }); + const remainingCommit = vi.fn(async () => undefined); primePluginUpdate( nextRuntimeConfig, [{ pluginId: "alpha", status: "updated", message: "Updated alpha -> 1.1.0" }], true, + [ + { commit: failedCommit, rollback }, + { commit: remainingCommit, rollback }, + ], ); updateNpmInstalledHookPacksMock.mockResolvedValue({ outcomes: [], @@ -1461,7 +1555,9 @@ describe("plugins cli update", () => { config: nextRuntimeConfig, }); - await runPluginsCommand(["plugins", "update", "alpha"]); + await expect(runPluginsCommand(["plugins", "update", "alpha"])).rejects.toThrow( + "Plugin install transaction commit failed", + ); const updateParams = expectSingleCallParams(updateNpmInstalledPluginsMock); expect(updateParams.config).toEqual(runtimeConfig); @@ -1479,12 +1575,10 @@ describe("plugins cli update", () => { }, }), }); - expect(refreshPluginRegistryMock).toHaveBeenCalledWith({ - config: {}, - installRecords: nextConfig.plugins?.installs, - reason: "source-changed", - }); - expectRestartNoticeLogged(); + expect(failedCommit).toHaveBeenCalledOnce(); + expect(remainingCommit).toHaveBeenCalledOnce(); + expect(rollback).not.toHaveBeenCalled(); + expect(refreshPluginRegistryMock).not.toHaveBeenCalled(); }); it("exits non-zero when a plugin update reports an error after persisting successes", async () => { diff --git a/src/cli/plugins-uninstall-command.ts b/src/cli/plugins-uninstall-command.ts index 3bf22421ea90..0f5166a2bcb2 100644 --- a/src/cli/plugins-uninstall-command.ts +++ b/src/cli/plugins-uninstall-command.ts @@ -64,6 +64,9 @@ async function runPluginUninstallCommandUnlocked( assertConfigWriteAllowedInCurrentMode(); } + const { loadInstalledPluginIndex } = await import("../plugins/installed-plugin-index.js"); + const { resolveInstalledPluginPackageOwnership } = + await import("../plugins/installed-plugin-package-ownership.js"); const { loadInstalledPluginIndexInstallRecords, removePluginInstallRecordFromRecords, @@ -77,10 +80,11 @@ async function runPluginUninstallCommandUnlocked( formatUninstallSlotResetPreview, planPluginUninstall, pluginUninstallTargetExists, - prepareConfigForPendingPluginDirectoryRemoval, resolveUninstallChannelConfigKeys, UNINSTALL_ACTION_LABELS, } = await import("../plugins/uninstall.js"); + const { prepareConfigForPendingPluginDirectoryRemovalSet, recordPluginPackageUninstallPlan } = + await import("../plugins/uninstall-package-plan.js"); const { commitPluginInstallRecordsWithConfig } = await import("../plugins/install-record-commit.js"); const { selectInstallMutationWriteOptions } = await import("../plugins/install-persistence.js"); @@ -102,6 +106,7 @@ async function runPluginUninstallCommandUnlocked( { command: "uninstall" }, ); const cfg = withPluginInstallRecords(sourceConfig, installRecords); + const installedIndex = loadInstalledPluginIndex({ config: cfg, installRecords }); const report = tracePluginLifecyclePhase( "plugin registry snapshot", () => buildPluginSnapshotReport({ config: cfg }), @@ -124,15 +129,42 @@ async function runPluginUninstallCommandUnlocked( runtime.exit(1); return; } - const { plugin, pluginId } = selection.value; - const channelIds = plugin?.channelIds; - const initialPlan = planPluginUninstall({ - config: cfg, - pluginId, - channelIds, - deleteFiles: !keepFiles, - extensionsDir, - }); + const { plugin } = selection.value; + const requestedPluginId = selection.value.pluginId; + const ownership = resolveInstalledPluginPackageOwnership(installedIndex, requestedPluginId); + if (!ownership.ok) { + runtime.error(ownership.error); + runtime.exit(1); + return; + } + const { installOwner: pluginId, pluginIds: ownedPluginIds } = ownership.value; + const channelIds = + ownedPluginIds.length === 1 && ownedPluginIds[0] === requestedPluginId + ? plugin?.channelIds + : [ + ...new Set( + ownedPluginIds.flatMap( + (entryId) => report.plugins.find((entry) => entry.id === entryId)?.channelIds ?? [], + ), + ), + ]; + const initialPlan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: cfg, + pluginId, + ...(channelIds !== undefined ? { channelIds } : {}), + deleteFiles: !keepFiles, + extensionsDir, + }, + { + runtimePluginIds: ownedPluginIds, + runtimeLoadPaths: ownedPluginIds.flatMap( + (entryId) => report.plugins.find((entry) => entry.id === entryId)?.source ?? [], + ), + }, + ), + ); if (!initialPlan.ok) { if (plugin) { runtime.error( @@ -186,6 +218,11 @@ async function runPluginUninstallCommandUnlocked( runtime.log( `Plugin: ${theme.command(pluginName)}${pluginName !== pluginId ? theme.muted(` (${pluginId})`) : ""}`, ); + if (ownedPluginIds.length > 1 || requestedPluginId !== pluginId) { + runtime.log( + `Package owner: ${theme.command(pluginId)}; all entries will be removed: ${ownedPluginIds.join(", ")}`, + ); + } runtime.log(`Will remove: ${preview.length > 0 ? preview.join(", ") : "(nothing)"}`); const { collectClawPluginUninstallWarnings } = @@ -208,7 +245,11 @@ async function runPluginUninstallCommandUnlocked( if (!opts.force) { let confirmed: boolean; try { - confirmed = await promptYesNo(`Uninstall plugin "${pluginId}"?`); + confirmed = await promptYesNo( + ownedPluginIds.length > 1 + ? `Uninstall plugin package "${pluginId}" and all entries?` + : `Uninstall plugin "${pluginId}"?`, + ); } catch (error) { if (isPromptInputClosedError(error, PromptInputClosedError)) { runtime.error( @@ -235,7 +276,10 @@ async function runPluginUninstallCommandUnlocked( let finalWriteOptions = mutationWriteOptions; let directoryResult = { directoryRemoved: false, warnings: [] as string[] }; if (plan.directoryRemoval) { - const disabledConfig = prepareConfigForPendingPluginDirectoryRemoval(sourceConfig, pluginId); + const disabledConfig = prepareConfigForPendingPluginDirectoryRemovalSet( + sourceConfig, + ownedPluginIds, + ); const disabledCommit = await tracePluginLifecyclePhaseAsync( "config disable", () => @@ -267,13 +311,23 @@ async function runPluginUninstallCommandUnlocked( const refreshedSnapshot = refreshedPrepared.snapshot; const refreshedSourceConfig = (refreshedSnapshot.sourceConfig ?? refreshedSnapshot.config) as OpenClawConfig; - const refreshedPlan = planPluginUninstall({ - config: withPluginInstallRecords(refreshedSourceConfig, installRecords), - pluginId, - channelIds, - deleteFiles: true, - extensionsDir, - }); + const refreshedPlan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: withPluginInstallRecords(refreshedSourceConfig, installRecords), + pluginId, + ...(channelIds !== undefined ? { channelIds } : {}), + deleteFiles: true, + extensionsDir, + }, + { + runtimePluginIds: ownedPluginIds, + runtimeLoadPaths: ownedPluginIds.flatMap( + (entryId) => report.plugins.find((entry) => entry.id === entryId)?.source ?? [], + ), + }, + ), + ); if (!refreshedPlan.ok) { throw new Error(refreshedPlan.error); } @@ -319,8 +373,12 @@ async function runPluginUninstallCommandUnlocked( directory: directoryResult.directoryRemoved, }); + const uninstalledSubject = + ownedPluginIds.length > 1 || requestedPluginId !== pluginId + ? `plugin package "${pluginId}" and entries ${ownedPluginIds.join(", ")}` + : `plugin "${pluginId}"`; runtime.log( - `Uninstalled plugin "${pluginId}". Removed: ${removed.length > 0 ? removed.join(", ") : "nothing"}.`, + `Uninstalled ${uninstalledSubject}. Removed: ${removed.length > 0 ? removed.join(", ") : "nothing"}.`, ); runtime.log("Restart the gateway to apply changes."); }; diff --git a/src/cli/plugins-update-command.ts b/src/cli/plugins-update-command.ts index 0d17035b158a..68efb715b586 100644 --- a/src/cli/plugins-update-command.ts +++ b/src/cli/plugins-update-command.ts @@ -30,13 +30,26 @@ import { commitPluginInstallRecordsOnly, commitPluginInstallRecordsWithConfig, } from "../plugins/install-record-commit.js"; +import { + requestDeferredPluginInstall, + resolvePluginInstallOwnerMigrations, + settlePluginInstallTransactions, + type PluginInstallTransaction, +} from "../plugins/install-transaction.js"; import { loadInstalledPluginIndexInstallRecords, withoutPluginInstallRecords, withPluginInstallRecords, } from "../plugins/installed-plugin-index-records.js"; +import { loadInstalledPluginIndex } from "../plugins/installed-plugin-index.js"; +import { resolveInstalledPluginPackageOwnership } from "../plugins/installed-plugin-package-ownership.js"; import { configReferencesNpmInstallPath } from "../plugins/installs.js"; import { withPluginLifecycleLease } from "../plugins/plugin-lifecycle-lease.js"; +import { + capturePluginPackageUpdateSnapshot, + pluginPackageUpdateMayMutateConfig, + reconcilePluginPackageUpdateConfig, +} from "../plugins/plugin-package-update.js"; import { refreshPluginRegistryAfterConfigMutation } from "../plugins/registry-refresh.js"; import { isPluginInstallRecordUpdateSource, @@ -225,6 +238,24 @@ async function runPluginUpdateCommandUnlocked(params: RunPluginUpdateCommandPara sourceCfg, pluginInstallRecords, ); + const installedPluginIndex = loadInstalledPluginIndex({ + config: cfgWithPluginInstallRecords, + installRecords: pluginInstallRecords, + }); + const installOwnerByPluginId = new Map(); + const rejectedPluginIds = new Map(); + for (const pluginId of new Set([ + ...installedPluginIndex.plugins.map((plugin) => plugin.pluginId), + ...Object.keys(pluginInstallRecords), + ])) { + const ownership = resolveInstalledPluginPackageOwnership(installedPluginIndex, pluginId); + if (!ownership.ok) { + rejectedPluginIds.set(pluginId, ownership.error); + continue; + } + installOwnerByPluginId.set(pluginId, ownership.value.installOwner); + installOwnerByPluginId.set(ownership.value.installOwner, ownership.value.installOwner); + } const configuredUpdateChannel = normalizeUpdateChannel(cfg.update?.channel) ?? undefined; const officialPluginUpdateChannel = resolveRegistryUpdateChannel({ configChannel: configuredUpdateChannel, @@ -239,9 +270,24 @@ async function runPluginUpdateCommandUnlocked(params: RunPluginUpdateCommandPara } const pluginSelection = resolvePluginUpdateSelection({ installs: pluginInstallRecords, + installOwnerByPluginId, + rejectedPluginIds, rawId: params.id, all: params.opts.all, }); + if (pluginSelection.error) { + defaultRuntime.error(pluginSelection.error); + return defaultRuntime.exit(1); + } + const packageUpdateSnapshotResult = capturePluginPackageUpdateSnapshot({ + index: installedPluginIndex, + installOwners: pluginSelection.pluginIds, + }); + if (!packageUpdateSnapshotResult.ok) { + defaultRuntime.error(packageUpdateSnapshotResult.error); + return defaultRuntime.exit(1); + } + const packageUpdateSnapshot = packageUpdateSnapshotResult.value; const selectedHooks = readHookInstalls(); const hookSelection = resolveHookPackUpdateSelection({ installs: selectedHooks, @@ -316,7 +362,14 @@ async function runPluginUpdateCommandUnlocked(params: RunPluginUpdateCommandPara ); // Manual update records stay in the index unless scoped-package compatibility // migrates authored references or moves an explicit prior managed root. - const pluginConfigMayMutate = pluginIdMigrationMayMutate || pluginLoadPathMayMutate; + const pluginConfigMayMutate = + pluginIdMigrationMayMutate || + pluginLoadPathMayMutate || + pluginPackageUpdateMayMutateConfig({ + config: mutationSnapshot.snapshot.sourceConfig, + index: installedPluginIndex, + snapshot: packageUpdateSnapshot, + }); const blockedReasons = new Set(); if (pluginConfigMayMutate && pluginMutation.mode === "blocked") { blockedReasons.add(pluginMutation.reason); @@ -346,140 +399,207 @@ async function runPluginUpdateCommandUnlocked(params: RunPluginUpdateCommandPara } } - const pluginResult = - pluginSelection.pluginIds.length > 0 - ? await updateNpmInstalledPlugins({ - config: cfgWithPluginInstallRecords, - pluginIds: pluginSelection.pluginIds, - specOverrides: pluginSelection.specOverrides, - dryRun: params.opts.dryRun, - updateChannel: params.opts.all ? undefined : configuredUpdateChannel, - officialPluginUpdateChannel, - syncOfficialPluginInstalls: params.opts.all ? true : undefined, - coreVersion: VERSION, - dangerouslyForceUnsafeInstall: params.opts.dangerouslyForceUnsafeInstall, - ...resolveClawHubRiskAcknowledgementCliOptions({ - acknowledgeClawHubRisk: params.opts.acknowledgeClawHubRisk, - action: "updating", - allowPrompt: !params.opts.dryRun, - }), - logger, - onIntegrityDrift: async (drift) => { - const specLabel = drift.resolvedSpec ?? drift.spec; - defaultRuntime.log( - theme.warn( - `Integrity drift detected for "${drift.pluginId}" (${specLabel})` + - `\nExpected: ${drift.expectedIntegrity}` + - `\nActual: ${drift.actualIntegrity}`, - ), - ); - if (drift.dryRun) { - return true; - } - return await promptYesNo(`Continue updating "${drift.pluginId}" with this artifact?`); - }, - }) - : { config: cfgWithPluginInstallRecords, changed: false, outcomes: [] }; - const hookResult = - hookSelection.hookIds.length > 0 - ? await updateNpmInstalledHookPacks({ - config: pluginResult.config, - hookIds: hookSelection.hookIds, - specOverrides: hookSelection.specOverrides, - dryRun: params.opts.dryRun, - logger, - onIntegrityDrift: async (drift) => { - const specLabel = drift.resolvedSpec ?? drift.spec; - defaultRuntime.log( - theme.warn( - `Integrity drift detected for hook pack "${drift.hookId}" (${specLabel})` + - `\nExpected: ${drift.expectedIntegrity}` + - `\nActual: ${drift.actualIntegrity}`, - ), - ); - if (drift.dryRun) { - return true; - } - return await promptYesNo( - `Continue updating hook pack "${drift.hookId}" with this artifact?`, - ); - }, - }) - : { config: pluginResult.config, changed: false, outcomes: [] }; + const deferredPluginTransactions: PluginInstallTransaction[] = []; + let pluginResult; + try { + pluginResult = + pluginSelection.pluginIds.length > 0 + ? await updateNpmInstalledPlugins( + requestDeferredPluginInstall( + { + config: cfgWithPluginInstallRecords, + pluginIds: pluginSelection.pluginIds, + specOverrides: pluginSelection.specOverrides, + dryRun: params.opts.dryRun, + updateChannel: params.opts.all ? undefined : configuredUpdateChannel, + officialPluginUpdateChannel, + syncOfficialPluginInstalls: params.opts.all ? true : undefined, + coreVersion: VERSION, + dangerouslyForceUnsafeInstall: params.opts.dangerouslyForceUnsafeInstall, + ...resolveClawHubRiskAcknowledgementCliOptions({ + acknowledgeClawHubRisk: params.opts.acknowledgeClawHubRisk, + action: "updating", + allowPrompt: !params.opts.dryRun, + }), + logger, + onIntegrityDrift: async (drift) => { + const specLabel = drift.resolvedSpec ?? drift.spec; + defaultRuntime.log( + theme.warn( + `Integrity drift detected for "${drift.pluginId}" (${specLabel})` + + `\nExpected: ${drift.expectedIntegrity}` + + `\nActual: ${drift.actualIntegrity}`, + ), + ); + if (drift.dryRun) { + return true; + } + return await promptYesNo( + `Continue updating "${drift.pluginId}" with this artifact?`, + ); + }, + }, + deferredPluginTransactions, + ), + ) + : { config: cfgWithPluginInstallRecords, changed: false, outcomes: [] }; + } catch (error) { + await settlePluginInstallTransactions(deferredPluginTransactions, "rollback"); + throw error; + } + const settlePluginTransactions = async (action: "commit" | "rollback") => { + await settlePluginInstallTransactions(deferredPluginTransactions, action); + }; + let packageCommitFinalized = false; + try { + if (pluginSelection.pluginIds.length > 0 && pluginResult.changed && !params.opts.dryRun) { + const nextInstallRecords = pluginResult.config.plugins?.installs ?? {}; + const afterIndex = loadInstalledPluginIndex({ + config: pluginResult.config, + installRecords: nextInstallRecords, + }); + const reconciled = reconcilePluginPackageUpdateConfig({ + config: pluginResult.config, + beforeIndex: installedPluginIndex, + afterIndex, + snapshot: packageUpdateSnapshot, + installOwnerMigrations: resolvePluginInstallOwnerMigrations(pluginResult), + }); + if (!reconciled.ok) { + await settlePluginTransactions("rollback"); + defaultRuntime.error(reconciled.error); + return defaultRuntime.exit(1); + } + pluginResult = { ...pluginResult, config: reconciled.config }; + } + const hookResult = + hookSelection.hookIds.length > 0 + ? await updateNpmInstalledHookPacks({ + config: pluginResult.config, + hookIds: hookSelection.hookIds, + specOverrides: hookSelection.specOverrides, + dryRun: params.opts.dryRun, + logger, + onIntegrityDrift: async (drift) => { + const specLabel = drift.resolvedSpec ?? drift.spec; + defaultRuntime.log( + theme.warn( + `Integrity drift detected for hook pack "${drift.hookId}" (${specLabel})` + + `\nExpected: ${drift.expectedIntegrity}` + + `\nActual: ${drift.actualIntegrity}`, + ), + ); + if (drift.dryRun) { + return true; + } + return await promptYesNo( + `Continue updating hook pack "${drift.hookId}" with this artifact?`, + ); + }, + }) + : { config: pluginResult.config, changed: false, outcomes: [] }; - const outcomeSummary = logPluginUpdateOutcomes({ - outcomes: [...pluginResult.outcomes, ...hookResult.outcomes], - log: (message) => defaultRuntime.log(message), - }); + const outcomeSummary = logPluginUpdateOutcomes({ + outcomes: [...pluginResult.outcomes, ...hookResult.outcomes], + log: (message) => defaultRuntime.log(message), + }); - if (!params.opts.dryRun && (pluginResult.changed || hookResult.changed)) { - const sourceSnapshot = mutationSnapshot ?? (await sourceSnapshotPromise); - const nextPluginInstallRecords = pluginResult.config.plugins?.installs ?? {}; - const shouldPersistPluginInstallIndex = - pluginResult.changed || Object.keys(pluginInstallRecords).length > 0; - const sourceShapedUpdateConfig = projectUpdaterResultOntoSourceConfig({ - runtimeBase: cfgWithPluginInstallRecords, - sourceBase: sourceCfgWithPluginInstallRecords, - updatedConfig: hookResult.config, - }); - // Plugin install records live in the persisted index. Preserve an authored - // empty plugins section so include ownership does not become a false mutation. - const nextConfig = withoutPluginInstallRecords(sourceShapedUpdateConfig, { - preserveEmptyPlugins: shouldPreserveEmptyPlugins({ - parsed: sourceSnapshot?.snapshot.parsed, - sourceConfig: sourceSnapshot?.snapshot.sourceConfig ?? {}, - }), - }); - let recordsOnlyPluginUpdate = false; - if (shouldPersistPluginInstallIndex) { - if (isDeepStrictEqual(nextConfig, sourceSnapshot?.snapshot.sourceConfig ?? sourceCfg)) { - await commitPluginInstallRecordsOnly({ - previousInstallRecords: persistedPluginInstallRecords, - nextInstallRecords: nextPluginInstallRecords, - nextConfig, - verifyConfigFresh: async () => { - await assertRecordsOnlyUpdateConfigFresh({ - baseHash: sourceSnapshot?.snapshot.hash, - writeOptions: sourceSnapshot?.writeOptions, - }); - }, + if (!params.opts.dryRun && (pluginResult.changed || hookResult.changed)) { + const sourceSnapshot = mutationSnapshot ?? (await sourceSnapshotPromise); + if (pluginResult.changed) { + const currentInstallRecords = await loadInstalledPluginIndexInstallRecords(); + const currentSnapshot = capturePluginPackageUpdateSnapshot({ + index: installedPluginIndex, + installOwners: pluginSelection.pluginIds, }); - recordsOnlyPluginUpdate = pluginResult.changed; + if ( + !isDeepStrictEqual(currentInstallRecords, persistedPluginInstallRecords) || + !currentSnapshot.ok || + !isDeepStrictEqual([...currentSnapshot.value], [...packageUpdateSnapshot]) + ) { + await settlePluginTransactions("rollback"); + defaultRuntime.error( + currentSnapshot.ok + ? "Plugin package ownership changed during update; no config or index changes were committed. Refresh the plugin registry and retry." + : currentSnapshot.error, + ); + return defaultRuntime.exit(1); + } + } + const nextPluginInstallRecords = pluginResult.config.plugins?.installs ?? {}; + const shouldPersistPluginInstallIndex = + pluginResult.changed || Object.keys(pluginInstallRecords).length > 0; + const sourceShapedUpdateConfig = projectUpdaterResultOntoSourceConfig({ + runtimeBase: cfgWithPluginInstallRecords, + sourceBase: sourceCfgWithPluginInstallRecords, + updatedConfig: hookResult.config, + }); + // Plugin install records live in the persisted index. Preserve an authored + // empty plugins section so include ownership does not become a false mutation. + const nextConfig = withoutPluginInstallRecords(sourceShapedUpdateConfig, { + preserveEmptyPlugins: shouldPreserveEmptyPlugins({ + parsed: sourceSnapshot?.snapshot.parsed, + sourceConfig: sourceSnapshot?.snapshot.sourceConfig ?? {}, + }), + }); + let recordsOnlyPluginUpdate = false; + if (shouldPersistPluginInstallIndex) { + if (isDeepStrictEqual(nextConfig, sourceSnapshot?.snapshot.sourceConfig ?? sourceCfg)) { + await commitPluginInstallRecordsOnly({ + previousInstallRecords: persistedPluginInstallRecords, + nextInstallRecords: nextPluginInstallRecords, + nextConfig, + verifyConfigFresh: async () => { + await assertRecordsOnlyUpdateConfigFresh({ + baseHash: sourceSnapshot?.snapshot.hash, + writeOptions: sourceSnapshot?.writeOptions, + }); + }, + }); + recordsOnlyPluginUpdate = pluginResult.changed; + } else { + await commitPluginInstallRecordsWithConfig({ + previousInstallRecords: persistedPluginInstallRecords, + nextInstallRecords: nextPluginInstallRecords, + nextConfig, + baseHash: sourceSnapshot?.snapshot.hash, + writeOptions: { + ...sourceSnapshot?.writeOptions, + afterWrite: { mode: "restart", reason: "plugin source changed" }, + }, + }); + } } else { - await commitPluginInstallRecordsWithConfig({ - previousInstallRecords: persistedPluginInstallRecords, - nextInstallRecords: nextPluginInstallRecords, + await replaceConfigFile({ nextConfig, baseHash: sourceSnapshot?.snapshot.hash, - writeOptions: { - ...sourceSnapshot?.writeOptions, - afterWrite: { mode: "restart", reason: "plugin source changed" }, - }, + writeOptions: sourceSnapshot?.writeOptions, }); } - } else { - await replaceConfigFile({ - nextConfig, - baseHash: sourceSnapshot?.snapshot.hash, - writeOptions: sourceSnapshot?.writeOptions, - }); - } - if (pluginResult.changed) { - await refreshPluginRegistryAfterConfigMutation({ - config: nextConfig, - reason: "source-changed", - installRecords: nextPluginInstallRecords, - invalidateRuntimeCache: false, - logger, - }); - if (recordsOnlyPluginUpdate) { - await notifyGatewayPluginMetadataChanged(cfg); + packageCommitFinalized = true; + await settlePluginTransactions("commit"); + if (pluginResult.changed) { + await refreshPluginRegistryAfterConfigMutation({ + config: nextConfig, + reason: "source-changed", + installRecords: nextPluginInstallRecords, + invalidateRuntimeCache: false, + logger, + }); + if (recordsOnlyPluginUpdate) { + await notifyGatewayPluginMetadataChanged(cfg); + } } + defaultRuntime.log("Restart the gateway to load plugins and hooks."); } - defaultRuntime.log("Restart the gateway to load plugins and hooks."); - } - if (outcomeSummary.hasErrors) { - defaultRuntime.exit(1); + if (outcomeSummary.hasErrors) { + defaultRuntime.exit(1); + } + } catch (error) { + if (!packageCommitFinalized) { + await settlePluginTransactions("rollback"); + } + throw error; } } diff --git a/src/cli/plugins-update-selection.test.ts b/src/cli/plugins-update-selection.test.ts index fdc0e37ab11f..a0425fc3b88a 100644 --- a/src/cli/plugins-update-selection.test.ts +++ b/src/cli/plugins-update-selection.test.ts @@ -147,6 +147,65 @@ describe("resolvePluginUpdateSelection", () => { }); }); + it("resolves a packed child update to its tracked package owner", () => { + expect( + resolvePluginUpdateSelection({ + installs: { + pack: createNpmInstall({ spec: "@acme/pack", resolvedName: "@acme/pack" }), + }, + installOwnerByPluginId: new Map([ + ["pack/one", "pack"], + ["pack/two", "pack"], + ]), + rawId: "pack/two", + }), + ).toEqual({ pluginIds: ["pack"] }); + }); + + it("does not infer a packed child owner when owner metadata is missing", () => { + expect( + resolvePluginUpdateSelection({ + installs: { + pack: createNpmInstall({ spec: "@acme/pack", resolvedName: "@acme/pack" }), + }, + rawId: "pack/two", + }), + ).toEqual({ pluginIds: [] }); + }); + + it("rejects an ambiguous child before exact install-record selection", () => { + expect( + resolvePluginUpdateSelection({ + installs: { + "pack/one": createNpmInstall({ spec: "@acme/pack" }), + "pack/two": createNpmInstall({ spec: "@acme/pack" }), + }, + rejectedPluginIds: new Map([ + ["pack/one", "ambiguous pack/one"], + ["pack/two", "ambiguous pack/two"], + ]), + rawId: "pack/one", + }), + ).toEqual({ pluginIds: [], error: "ambiguous pack/one" }); + }); + + it("rejects an ambiguous package owner for targeted and update-all selection", () => { + const installs = { + pack: createNpmInstall({ spec: "@acme/pack" }), + stable: createNpmInstall({ spec: "@acme/stable" }), + }; + const rejectedPluginIds = new Map([["pack", "ambiguous pack"]]); + + expect(resolvePluginUpdateSelection({ installs, rejectedPluginIds, rawId: "pack" })).toEqual({ + pluginIds: [], + error: "ambiguous pack", + }); + expect(resolvePluginUpdateSelection({ installs, rejectedPluginIds, all: true })).toEqual({ + pluginIds: [], + error: "ambiguous pack", + }); + }); + it("maps prototype-named npm packages by own install records", () => { expect( resolvePluginUpdateSelection({ diff --git a/src/cli/plugins-update-selection.ts b/src/cli/plugins-update-selection.ts index 48d6c70a7633..14171aac1ece 100644 --- a/src/cli/plugins-update-selection.ts +++ b/src/cli/plugins-update-selection.ts @@ -11,19 +11,39 @@ import { /** Resolve a plugin update target and optional npm spec override from CLI input. */ export function resolvePluginUpdateSelection(params: { installs: Record; + installOwnerByPluginId?: ReadonlyMap; + rejectedPluginIds?: ReadonlyMap; rawId?: string; all?: boolean; -}): { pluginIds: string[]; specOverrides?: Record } { +}): { pluginIds: string[]; specOverrides?: Record; error?: string } { if (params.all) { - return { pluginIds: Object.keys(params.installs) }; + const rejectedOwners = Object.keys(params.installs).filter((pluginId) => + params.rejectedPluginIds?.has(pluginId), + ); + if (rejectedOwners.length > 0) { + return { + pluginIds: [], + error: params.rejectedPluginIds?.get(rejectedOwners[0]!), + }; + } + return { + pluginIds: Object.keys(params.installs), + }; } if (!params.rawId) { return { pluginIds: [] }; } + if (params.rejectedPluginIds?.has(params.rawId)) { + return { pluginIds: [], error: params.rejectedPluginIds.get(params.rawId) }; + } if (Object.hasOwn(params.installs, params.rawId)) { return { pluginIds: [params.rawId] }; } + const installOwner = params.installOwnerByPluginId?.get(params.rawId); + if (installOwner && Object.hasOwn(params.installs, installOwner)) { + return { pluginIds: [installOwner] }; + } const parsedSpec = parseRegistryNpmSpec(params.rawId); if (!parsedSpec) { @@ -40,6 +60,9 @@ export function resolvePluginUpdateSelection(params: { if (!pluginId) { return { pluginIds: [] }; } + if (params.rejectedPluginIds?.has(pluginId)) { + return { pluginIds: [], error: params.rejectedPluginIds.get(pluginId) }; + } return { pluginIds: [pluginId], specOverrides: { diff --git a/src/commands/doctor/shared/plugin-registry-migration.test.ts b/src/commands/doctor/shared/plugin-registry-migration.test.ts index 67bf24c20cd2..05edc4ee82e3 100644 --- a/src/commands/doctor/shared/plugin-registry-migration.test.ts +++ b/src/commands/doctor/shared/plugin-registry-migration.test.ts @@ -4,6 +4,7 @@ import path from "node:path"; import { createRequireRecord } from "openclaw/plugin-sdk/test-fixtures"; import { afterEach, describe, expect, it, vi } from "vitest"; import type { OpenClawConfig } from "../../../config/types.openclaw.js"; +import { recordPluginCandidateInstallOwner } from "../../../plugins/candidate-install-owner.js"; import type { PluginCandidate } from "../../../plugins/discovery.js"; import { readPersistedInstalledPluginIndex, @@ -40,7 +41,11 @@ function createCandidate( rootDir: string, id = "demo", origin: PluginCandidate["origin"] = "global", - options: { enabledByDefault?: boolean; manifest?: Record } = {}, + options: { + enabledByDefault?: boolean; + installOwner?: string; + manifest?: Record; + } = {}, ): PluginCandidate { fs.writeFileSync( path.join(rootDir, "index.ts"), @@ -59,12 +64,15 @@ function createCandidate( }), "utf8", ); - return { - idHint: id, - source: path.join(rootDir, "index.ts"), - rootDir, - origin, - }; + return recordPluginCandidateInstallOwner( + { + idHint: id, + source: path.join(rootDir, "index.ts"), + rootDir, + origin, + }, + options.installOwner, + ); } function createCurrentIndex(): InstalledPluginIndex { @@ -454,7 +462,7 @@ describe("plugin registry install migration", () => { const result = await migratePluginRegistryForInstall({ stateDir, - candidates: [createCandidate(pluginDir)], + candidates: [createCandidate(pluginDir, "demo", "global", { installOwner: "demo" })], readConfig: async () => ({ plugins: { entries: { diff --git a/src/infra/install-package-dir.test.ts b/src/infra/install-package-dir.test.ts index f51a7c65f194..5af8a50e5dae 100644 --- a/src/infra/install-package-dir.test.ts +++ b/src/infra/install-package-dir.test.ts @@ -5,7 +5,11 @@ import path from "node:path"; import { afterEach, describe, expect, it, vi } from "vitest"; import { runCommandWithTimeout, type CommandOptions, type SpawnResult } from "../process/exec.js"; import { createSuiteTempRootTracker } from "../test-helpers/temp-dir.js"; -import { installPackageDir } from "./install-package-dir.js"; +import { + installPackageDir, + requestDeferredPackageDirInstall, + resolvePackageDirInstallTransaction, +} from "./install-package-dir.js"; vi.mock("../process/exec.js", async () => { const actual = await vi.importActual("../process/exec.js"); @@ -812,4 +816,36 @@ describe("installPackageDir", () => { } }, ); + + it("restores the previous package when a deferred update rolls back", async () => { + await fixtureRootTracker.setup(); + const fixtureRoot = await fixtureRootTracker.make("deferred-rollback"); + const sourceDir = path.join(fixtureRoot, "source"); + const targetDir = path.join(fixtureRoot, "plugins", "demo"); + await fs.mkdir(sourceDir, { recursive: true }); + await fs.mkdir(targetDir, { recursive: true }); + await fs.writeFile(path.join(sourceDir, "version.txt"), "v2", "utf8"); + await fs.writeFile(path.join(targetDir, "version.txt"), "v1", "utf8"); + + const result = await installPackageDir( + requestDeferredPackageDirInstall({ + sourceDir, + targetDir, + mode: "update", + timeoutMs: 1_000, + copyErrorPrefix: "failed to copy plugin", + hasDeps: false, + depsLogMessage: "", + }), + ); + + expect(result.ok).toBe(true); + const transaction = result.ok ? resolvePackageDirInstallTransaction(result) : undefined; + if (!transaction) { + throw new Error("expected deferred package transaction"); + } + expect(await fs.readFile(path.join(targetDir, "version.txt"), "utf8")).toBe("v2"); + await transaction.rollback(); + expect(await fs.readFile(path.join(targetDir, "version.txt"), "utf8")).toBe("v1"); + }); }); diff --git a/src/infra/install-package-dir.ts b/src/infra/install-package-dir.ts index bda4f9f10656..7b756c067af1 100644 --- a/src/infra/install-package-dir.ts +++ b/src/infra/install-package-dir.ts @@ -163,6 +163,53 @@ async function resolveInstallPublishTarget(params: { }; } +type PackageDirInstallTransaction = { + commit(): Promise; + rollback(): Promise; +}; + +const PACKAGE_DIR_INSTALL_TRANSACTION = Symbol.for("openclaw.packageDirInstallTransaction"); +const PACKAGE_DIR_INSTALL_TRANSACTION_REQUEST = Symbol.for( + "openclaw.packageDirInstallTransactionRequest", +); + +export function requestDeferredPackageDirInstall(params: T): T { + Object.defineProperty(params, PACKAGE_DIR_INSTALL_TRANSACTION_REQUEST, { + configurable: false, + enumerable: true, + value: true, + }); + return params; +} + +function isPackageDirInstallCommitDeferred(params: object): boolean { + return ( + (params as { [PACKAGE_DIR_INSTALL_TRANSACTION_REQUEST]?: true })[ + PACKAGE_DIR_INSTALL_TRANSACTION_REQUEST + ] === true + ); +} + +function attachPackageDirInstallTransaction( + result: T, + transaction: PackageDirInstallTransaction, +): T { + Object.defineProperty(result, PACKAGE_DIR_INSTALL_TRANSACTION, { + configurable: false, + enumerable: true, + value: transaction, + }); + return result; +} + +export function resolvePackageDirInstallTransaction( + result: object, +): PackageDirInstallTransaction | undefined { + return (result as { [PACKAGE_DIR_INSTALL_TRANSACTION]?: PackageDirInstallTransaction })[ + PACKAGE_DIR_INSTALL_TRANSACTION + ]; +} + /** * Publishes a package directory into an install target via a staged copy. * Update mode backs up the existing target, runs optional validation hooks, @@ -183,6 +230,7 @@ export async function installPackageDir(params: { installedDir: string, ) => Promise<{ ok: true } | { ok: false; error: string; code?: string }>; }): Promise<{ ok: true } | { ok: false; error: string; code?: string }> { + const deferCommit = isPackageDirInstallCommitDeferred(params); params.logger?.info?.(`Installing to ${params.targetDir}…`); const installBaseDir = path.dirname(params.targetDir); let initialInstallBaseRealPath: string; @@ -364,14 +412,46 @@ export async function installPackageDir(params: { backupDir = null; } } - if (backupDir) { + const retainedBackupDir = backupDir; + if (backupDir && !deferCommit) { await fs.rm(backupDir, { recursive: true, force: true }).catch(() => undefined); } if (stageDir) { await cleanupInstallTempDir(stageDir); } - return { ok: true }; + if (!deferCommit) { + return { ok: true }; + } + let settled = false; + return attachPackageDirInstallTransaction( + { ok: true }, + { + async commit() { + if (settled) { + return; + } + settled = true; + if (retainedBackupDir) { + await fs.rm(retainedBackupDir, { recursive: true, force: true }).catch(() => undefined); + } + }, + async rollback() { + if (settled) { + return; + } + settled = true; + await fs.rm(canonicalTargetDir, { recursive: true, force: true }); + if (retainedBackupDir) { + await movePathWithCopyFallback({ + from: retainedBackupDir, + sourceHardlinks, + to: canonicalTargetDir, + }); + } + }, + }, + ); } /** diff --git a/src/plugins/candidate-install-owner.ts b/src/plugins/candidate-install-owner.ts new file mode 100644 index 000000000000..55f92445e7f1 --- /dev/null +++ b/src/plugins/candidate-install-owner.ts @@ -0,0 +1,56 @@ +const PLUGIN_CANDIDATE_INSTALL_OWNER = Symbol.for("openclaw.pluginCandidateInstallOwner"); +const PLUGIN_INSTALL_OWNER_LOOKUP = Symbol.for("openclaw.pluginInstallOwnerLookup"); + +type PluginCandidateInstallOwner = { installOwner?: string; ambiguous?: true }; + +export function recordPluginCandidateInstallOwner( + candidate: T, + installOwner: string | undefined, + ambiguous = false, +): T { + if (!installOwner && !ambiguous) { + return candidate; + } + Object.defineProperty(candidate, PLUGIN_CANDIDATE_INSTALL_OWNER, { + configurable: true, + enumerable: true, + value: ambiguous ? { ambiguous: true } : { installOwner }, + }); + return candidate; +} + +function readPluginCandidateInstallOwner( + candidate: object, +): PluginCandidateInstallOwner | undefined { + return (candidate as { [PLUGIN_CANDIDATE_INSTALL_OWNER]?: PluginCandidateInstallOwner })[ + PLUGIN_CANDIDATE_INSTALL_OWNER + ]; +} + +export function resolvePluginCandidateInstallOwner(candidate: object): string | undefined { + return readPluginCandidateInstallOwner(candidate)?.installOwner; +} + +export function isPluginCandidateInstallOwnerAmbiguous(candidate: object): boolean { + return readPluginCandidateInstallOwner(candidate)?.ambiguous === true; +} + +export function recordPluginInstallOwnerLookup( + params: T, + installOwnerByPluginId: ReadonlyMap, +): T { + Object.defineProperty(params, PLUGIN_INSTALL_OWNER_LOOKUP, { + configurable: false, + enumerable: true, + value: installOwnerByPluginId, + }); + return params; +} + +export function resolvePluginInstallOwnerLookup( + params: object, +): ReadonlyMap | undefined { + return (params as { [PLUGIN_INSTALL_OWNER_LOOKUP]?: ReadonlyMap })[ + PLUGIN_INSTALL_OWNER_LOOKUP + ]; +} diff --git a/src/plugins/clawhub.ts b/src/plugins/clawhub.ts index 1318e79dcced..defc378a7f95 100644 --- a/src/plugins/clawhub.ts +++ b/src/plugins/clawhub.ts @@ -52,6 +52,7 @@ import type { RuntimeVersionEnv } from "../version.js"; import { CLAWHUB_INSTALL_ERROR_CODE, type ClawHubInstallErrorCode } from "./clawhub-error-codes.js"; import type { ClawHubPluginInstallRecordFields } from "./clawhub-install-records.js"; import type { InstallSafetyOverrides } from "./install-security-scan.js"; +import { copyPluginInstallTransactionRequest } from "./install-transaction.js"; import { installPluginFromArchive, PLUGIN_INSTALL_ERROR_CODE, @@ -1441,29 +1442,31 @@ export async function installPluginFromClawHub( params.logger?.info?.( `Downloading ${detail.package?.family === "bundle-plugin" ? "bundle" : "plugin"} ${releaseLabel} from ClawHub…`, ); - const installResult = await installPluginFromArchive({ - archivePath: archive.archivePath, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - trustedSourceLinkedOfficialInstall: - officialClawHubPackage || isTrustedSourceLinkedOfficialPackage(detail.package!), - config: params.config, - logger: params.logger, - mode: params.mode, - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - dryRun: params.dryRun, - expectedPluginId: runtimeIdResolution.expectedPluginId, - installPolicyRequest: { - kind: "plugin-archive", - requestedSpecifier: params.spec, - source: { - kind: "clawhub", - authority: officialClawHubPackage ? "official" : clawhubAuthority, - mutable: false, - network: true, + const installResult = await installPluginFromArchive( + copyPluginInstallTransactionRequest(params, { + archivePath: archive.archivePath, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + trustedSourceLinkedOfficialInstall: + officialClawHubPackage || isTrustedSourceLinkedOfficialPackage(detail.package!), + config: params.config, + logger: params.logger, + mode: params.mode, + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + dryRun: params.dryRun, + expectedPluginId: runtimeIdResolution.expectedPluginId, + installPolicyRequest: { + kind: "plugin-archive", + requestedSpecifier: params.spec, + source: { + kind: "clawhub", + authority: officialClawHubPackage ? "official" : clawhubAuthority, + mutable: false, + network: true, + }, }, - }, - }); + }), + ); if (!installResult.ok) { return installResult; } diff --git a/src/plugins/discovery.test.ts b/src/plugins/discovery.test.ts index cc1811876b29..144933d80d34 100644 --- a/src/plugins/discovery.test.ts +++ b/src/plugins/discovery.test.ts @@ -5,6 +5,10 @@ import path from "node:path"; import { bundledDistPluginFile } from "openclaw/plugin-sdk/test-fixtures"; import { afterEach, describe, expect, it, vi } from "vitest"; import type { PluginInstallRecord } from "../config/types.plugins.js"; +import { + isPluginCandidateInstallOwnerAmbiguous, + resolvePluginCandidateInstallOwner, +} from "./candidate-install-owner.js"; import { discoverOpenClawPlugins } from "./discovery.js"; import * as pluginHardlinkPolicy from "./hardlink-policy.js"; import { loadPluginManifestRegistryCore } from "./manifest-registry.js"; @@ -351,24 +355,20 @@ function expectNoDiagnostic(params: { expect(matched).toBe(false); } -function expectCandidateFields( - candidate: - | { - idHint?: string; - format?: string; - bundleFormat?: string; - source?: string; - rootDir?: string; - origin?: string; - } - | undefined, - expected: Record, -) { +function expectCandidateFields(candidate: object | undefined, expected: Record) { if (!candidate) { throw new Error("Expected plugin candidate"); } for (const [key, value] of Object.entries(expected)) { - expect(candidate[key as keyof typeof candidate], key).toBe(value); + if (key === "installOwner") { + expect(resolvePluginCandidateInstallOwner(candidate), key).toBe(value); + continue; + } + if (key === "installOwnerAmbiguous") { + expect(isPluginCandidateInstallOwnerAmbiguous(candidate), key).toBe(value); + continue; + } + expect((candidate as Record)[key], key).toBe(value); } } @@ -1033,14 +1033,112 @@ describe("discoverOpenClawPlugins", () => { ); expectCandidateFields(requireCandidateById(result.candidates, "linked-source-pack"), { setupSource: fs.realpathSync(path.join(pluginDir, "src", "setup-entry.ts")), + installOwner: "linked-source-pack", }); expectNoDiagnostic({ diagnostics: result.diagnostics, pluginId: "linked-source-pack", messageIncludes: "requires compiled runtime output", }); + + const configured = await discoverWithStateDir(stateDir, { + extraPaths: [pluginDir], + installRecords, + }); + expectCandidateFields(requireCandidateById(configured.candidates, "linked-source-pack"), { + origin: "config", + installOwner: "linked-source-pack", + }); + + const ambiguous = await discoverWithStateDir(stateDir, { + installRecords: { + ...installRecords, + "other-owner": installRecords["linked-source-pack"], + }, + }); + const ambiguousCandidate = requireCandidateById(ambiguous.candidates, "linked-source-pack"); + expect(resolvePluginCandidateInstallOwner(ambiguousCandidate)).toBeUndefined(); + expect(isPluginCandidateInstallOwnerAmbiguous(ambiguousCandidate)).toBe(true); + expect( + ambiguous.diagnostics.some((diagnostic) => + diagnostic.message.includes("multiple plugin install records claim the same package path"), + ), + ).toBe(true); }); + it.runIf(canCreateDirectorySymlinks)( + "fails closed when aliased install paths claim the same package", + async () => { + const stateDir = makeTempDir(); + const pluginDir = path.join(stateDir, "extensions", "aliased-pack"); + const aliasDir = path.join(stateDir, "aliased-pack-link"); + mkdirSafe(pluginDir); + writePluginPackageManifest({ + packageDir: pluginDir, + packageName: "@openclaw/aliased-pack", + extensions: ["./index.ts"], + }); + writePluginManifest({ pluginDir, id: "aliased-pack" }); + writePluginEntry(path.join(pluginDir, "index.ts")); + symlinkDirectory(pluginDir, aliasDir); + + const result = await discoverWithStateDir(stateDir, { + installRecords: { + "owner-one": { source: "path", sourcePath: pluginDir, installPath: pluginDir }, + "owner-two": { source: "path", sourcePath: aliasDir, installPath: aliasDir }, + }, + }); + + const candidate = requireCandidateById(result.candidates, "aliased-pack"); + expect(resolvePluginCandidateInstallOwner(candidate)).toBeUndefined(); + expect(isPluginCandidateInstallOwnerAmbiguous(candidate)).toBe(true); + expect( + result.diagnostics.some((diagnostic) => + diagnostic.message.includes( + "multiple plugin install records claim the same package path", + ), + ), + ).toBe(true); + }, + ); + + it.runIf(canCreateDirectorySymlinks)( + "keeps configured-path precedence while inheriting one physical package owner", + async () => { + const stateDir = makeTempDir(); + const pluginDir = path.join(stateDir, "extensions", "configured-alias-pack"); + const aliasDir = path.join(stateDir, "configured-alias-pack-link"); + mkdirSafe(pluginDir); + writePluginPackageManifest({ + packageDir: pluginDir, + packageName: "@openclaw/configured-alias-pack", + extensions: ["./one.ts", "./two.ts"], + }); + writePluginManifest({ pluginDir, id: "configured-alias-pack" }); + writePluginEntry(path.join(pluginDir, "one.ts")); + writePluginEntry(path.join(pluginDir, "two.ts")); + symlinkDirectory(pluginDir, aliasDir); + + const result = await discoverWithStateDir(stateDir, { + extraPaths: [aliasDir], + installRecords: { + "configured-alias-pack": { + source: "path", + sourcePath: pluginDir, + installPath: pluginDir, + }, + }, + }); + + for (const pluginId of ["configured-alias-pack/one", "configured-alias-pack/two"]) { + expectCandidateFields(requireCandidateById(result.candidates, pluginId), { + origin: "config", + installOwner: "configured-alias-pack", + }); + } + }, + ); + it("still requires compiled runtime output for tracked installed package plugins", async () => { const stateDir = makeTempDir(); const pluginDir = path.join(stateDir, "extensions", "source-only-pack"); @@ -2409,6 +2507,30 @@ describe("discoverOpenClawPlugins", () => { }); }); + it("preserves the package install owner for managed bundle candidates", async () => { + const stateDir = makeTempDir(); + const bundleDir = path.join(stateDir, "extensions", "package-owner"); + createBundleRoot(bundleDir, ".codex-plugin/plugin.json", { + name: "runtime-child", + skills: "skills", + }); + mkdirSafe(path.join(bundleDir, "skills")); + + const { candidates } = await discoverWithStateDir(stateDir, { + installRecords: { + "package-owner": { + source: "path", + sourcePath: bundleDir, + installPath: bundleDir, + }, + }, + }); + + expectCandidateFields(requireCandidateById(candidates, "runtime-child"), { + installOwner: "package-owner", + }); + }); + it.each([ { name: "falls back to legacy index discovery when a scanned bundle sidecar is malformed", diff --git a/src/plugins/discovery.ts b/src/plugins/discovery.ts index f4616a526ede..c8802eb06bc9 100644 --- a/src/plugins/discovery.ts +++ b/src/plugins/discovery.ts @@ -18,6 +18,11 @@ import { } from "./bundled-dir.js"; import { buildLegacyBundledRootPath } from "./bundled-load-path-aliases.js"; import { listBundledSourceOverlayDirs } from "./bundled-source-overlays.js"; +import { + isPluginCandidateInstallOwnerAmbiguous, + recordPluginCandidateInstallOwner, + resolvePluginCandidateInstallOwner, +} from "./candidate-install-owner.js"; import { shouldRejectHardlinkedPluginFiles } from "./hardlink-policy.js"; import { readLegacyNpmPluginDeclaration } from "./legacy-npm-declaration.js"; import type { PluginBundleFormat, PluginDiagnostic, PluginFormat } from "./manifest-types.js"; @@ -389,15 +394,31 @@ function createDiscoveryResult(): PluginDiscoveryResult { function mergeDiscoveryResult( target: PluginDiscoveryResult, source: PluginDiscoveryResult, - seenSources: Set, + candidatesBySource: Map, seenDiagnostics: Set, + realpathCache: Map, ): void { for (const candidate of source.candidates) { - const key = candidate.source; - if (seenSources.has(key)) { + // Configured aliases keep their precedence, but lifecycle ownership follows + // the one physical package entry rather than its textual path spelling. + const key = safeRealpathSync(candidate.source, realpathCache) ?? path.resolve(candidate.source); + const existing = candidatesBySource.get(key); + if (existing) { + const existingOwner = resolvePluginCandidateInstallOwner(existing); + const candidateOwner = resolvePluginCandidateInstallOwner(candidate); + const ownerConflict = existingOwner && candidateOwner && existingOwner !== candidateOwner; + if ( + isPluginCandidateInstallOwnerAmbiguous(existing) || + isPluginCandidateInstallOwnerAmbiguous(candidate) || + ownerConflict + ) { + recordPluginCandidateInstallOwner(existing, undefined, true); + } else if (candidateOwner) { + recordPluginCandidateInstallOwner(existing, candidateOwner); + } continue; } - seenSources.add(key); + candidatesBySource.set(key, candidate); target.candidates.push(candidate); } for (const diagnostic of source.diagnostics) { @@ -468,6 +489,8 @@ function addMissingRequiredPluginDiagnostics( type InstalledPluginRecordPath = { path: string; requireBuiltRuntimeEntry: boolean; + installOwner?: string; + installOwnerAmbiguous?: true; }; function isLinkedLocalPluginRecord(params: { @@ -497,10 +520,11 @@ function collectInstalledPluginRecordPaths( installRecords: Record | undefined, env: NodeJS.ProcessEnv, realpathCache: Map, + diagnostics: PluginDiagnostic[], ): InstalledPluginRecordPath[] { const paths: InstalledPluginRecordPath[] = []; - const seen = new Set(); - for (const record of Object.values(installRecords ?? {})) { + const byPath = new Map(); + for (const [installOwner, record] of Object.entries(installRecords ?? {})) { const rawPath = typeof record.installPath === "string" && record.installPath.trim() ? record.installPath @@ -511,14 +535,33 @@ function collectInstalledPluginRecordPaths( continue; } const resolved = resolveUserPath(rawPath, env); - if (seen.has(resolved) || !fs.existsSync(resolved)) { + if (!fs.existsSync(resolved)) { continue; } - seen.add(resolved); - paths.push({ + const pathKey = safeRealpathSync(resolved, realpathCache) ?? path.resolve(resolved); + const requireBuiltRuntimeEntry = !isLinkedLocalPluginRecord({ record, env, realpathCache }); + const existing = byPath.get(pathKey); + if (existing) { + existing.requireBuiltRuntimeEntry ||= requireBuiltRuntimeEntry; + if (existing.installOwner !== installOwner) { + delete existing.installOwner; + existing.installOwnerAmbiguous = true; + diagnostics.push({ + level: "error", + source: resolved, + message: + "multiple plugin install records claim the same package path; refresh or reinstall the package before using managed lifecycle actions", + }); + } + continue; + } + const installedPath: InstalledPluginRecordPath = { path: resolved, - requireBuiltRuntimeEntry: !isLinkedLocalPluginRecord({ record, env, realpathCache }), - }); + requireBuiltRuntimeEntry, + installOwner, + }; + byPath.set(pathKey, installedPath); + paths.push(installedPath); } return paths; } @@ -737,6 +780,8 @@ function addCandidate(params: { seen: Set; idHint: string; effectivePluginId?: string; + installOwner?: string; + installOwnerAmbiguous?: true; diagnosticIdHint?: string; source: string; setupSource?: string; @@ -782,7 +827,7 @@ function addCandidate(params: { dependencies: manifest?.dependencies, optionalDependencies: manifest?.optionalDependencies, }); - params.candidates.push({ + const candidate = { idHint: params.idHint, ...(params.effectivePluginId ? { effectivePluginId: params.effectivePluginId } : {}), ...(params.diagnosticIdHint && params.diagnosticIdHint !== params.idHint @@ -810,7 +855,14 @@ function addCandidate(params: { ? { requiredPluginIds: params.requiredPluginIds } : {}), ...(params.requiredPluginSource ? { requiredPluginSource: params.requiredPluginSource } : {}), - }); + } satisfies PluginCandidate; + params.candidates.push( + recordPluginCandidateInstallOwner( + candidate, + params.installOwner, + params.installOwnerAmbiguous === true, + ), + ); } function discoverBundleInRoot(params: { @@ -819,6 +871,8 @@ function discoverBundleInRoot(params: { env: NodeJS.ProcessEnv; ownershipUid?: number | null; workspaceDir?: string; + installOwner?: string; + installOwnerAmbiguous?: true; manifest?: PackageManifest | null; candidates: PluginCandidate[]; diagnostics: PluginDiagnostic[]; @@ -863,6 +917,8 @@ function discoverBundleInRoot(params: { bundleFormat, ownershipUid: params.ownershipUid, workspaceDir: params.workspaceDir, + ...(params.installOwner ? { installOwner: params.installOwner } : {}), + ...(params.installOwnerAmbiguous ? { installOwnerAmbiguous: true } : {}), manifest: params.manifest, packageDir: params.rootDir, bundledManifestId: bundleManifest.manifest.id, @@ -935,6 +991,8 @@ type PluginDirectoryDiscoveryParams = { env: NodeJS.ProcessEnv; ownershipUid?: number | null; workspaceDir?: string; + installOwner?: string; + installOwnerAmbiguous?: true; requireBuiltRuntimeEntry?: boolean; managedPluginDirs?: Set; candidates: PluginCandidate[]; @@ -1030,6 +1088,8 @@ function discoverPluginDirectory(params: PluginDirectoryDiscoveryParams): boolea origin: params.origin, ownershipUid: params.ownershipUid, workspaceDir: params.workspaceDir, + ...(params.installOwner ? { installOwner: params.installOwner } : {}), + ...(params.installOwnerAmbiguous ? { installOwnerAmbiguous: true } : {}), manifest, packageDir: dir, requiredPluginIds: candidateManifest?.manifest.requiresPlugins, @@ -1097,6 +1157,8 @@ function discoverPluginDirectory(params: PluginDirectoryDiscoveryParams): boolea env: params.env, ownershipUid: params.ownershipUid, workspaceDir: params.workspaceDir, + ...(params.installOwner ? { installOwner: params.installOwner } : {}), + ...(params.installOwnerAmbiguous ? { installOwnerAmbiguous: true } : {}), manifest, candidates: params.candidates, diagnostics: params.diagnostics, @@ -1123,6 +1185,8 @@ function discoverInDirectory(params: { env: NodeJS.ProcessEnv; ownershipUid?: number | null; workspaceDir?: string; + installOwner?: string; + installOwnerAmbiguous?: true; requireBuiltRuntimeEntry?: boolean; managedPluginDirs?: Set; skipRootDirKeys?: Set; @@ -1179,6 +1243,8 @@ function discoverInDirectory(params: { origin: params.origin, ownershipUid: params.ownershipUid, workspaceDir: params.workspaceDir, + ...(params.installOwner ? { installOwner: params.installOwner } : {}), + ...(params.installOwnerAmbiguous ? { installOwnerAmbiguous: true } : {}), realpathCache: params.realpathCache, }); continue; @@ -1277,6 +1343,8 @@ function discoverFromPath(params: { origin: PluginOrigin; ownershipUid?: number | null; workspaceDir?: string; + installOwner?: string; + installOwnerAmbiguous?: true; requireBuiltRuntimeEntry?: boolean; managedPluginDirs?: Set; skipRootDirKeys?: Set; @@ -1318,6 +1386,8 @@ function discoverFromPath(params: { origin: params.origin, ownershipUid: params.ownershipUid, workspaceDir: params.workspaceDir, + ...(params.installOwner ? { installOwner: params.installOwner } : {}), + ...(params.installOwnerAmbiguous ? { installOwnerAmbiguous: true } : {}), realpathCache: params.realpathCache, }); return; @@ -1570,6 +1640,7 @@ export function discoverOpenClawPlugins(params: { params.installRecords, env, realpathCache, + result.diagnostics, ); const installedPluginDirKeys = collectManagedPluginDirKeys( installedPaths.map((installedPath) => installedPath.path), @@ -1585,6 +1656,8 @@ export function discoverOpenClawPlugins(params: { origin: "global", ownershipUid: params.ownershipUid, workspaceDir, + ...(installedPath.installOwner ? { installOwner: installedPath.installOwner } : {}), + ...(installedPath.installOwnerAmbiguous ? { installOwnerAmbiguous: true } : {}), requireBuiltRuntimeEntry: installedPath.requireBuiltRuntimeEntry, managedPluginDirs, scanFiles: true, @@ -1617,10 +1690,10 @@ export function discoverOpenClawPlugins(params: { { scope: "shared" }, ); const result = createDiscoveryResult(); - const seenSources = new Set(); + const candidatesBySource = new Map(); const seenDiagnostics = new Set(); - mergeDiscoveryResult(result, scopedResult, seenSources, seenDiagnostics); - mergeDiscoveryResult(result, sharedResult, seenSources, seenDiagnostics); + mergeDiscoveryResult(result, scopedResult, candidatesBySource, seenDiagnostics, realpathCache); + mergeDiscoveryResult(result, sharedResult, candidatesBySource, seenDiagnostics, realpathCache); addMissingRequiredPluginDiagnostics(result, { env, realpathCache }); return result; } diff --git a/src/plugins/git-install.ts b/src/plugins/git-install.ts index aa18a185229b..4348e06e881a 100644 --- a/src/plugins/git-install.ts +++ b/src/plugins/git-install.ts @@ -8,6 +8,11 @@ import { normalizeOptionalString } from "@openclaw/normalization-core/string-coe import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js"; import { sha256HexPrefixCore } from "../infra/crypto-digest.js"; import { pathExists } from "../infra/fs-safe.js"; +import { + installPackageDir, + requestDeferredPackageDirInstall, + resolvePackageDirInstallTransaction, +} from "../infra/install-package-dir.js"; import { withInstallWorkspace } from "../infra/install-source-utils.js"; import { replaceDirectoryAtomic } from "../infra/replace-file.js"; import { @@ -22,6 +27,11 @@ import { type InstallSafetyOverrides, type InstallSecurityScanResult, } from "./install-security-scan.js"; +import { + attachPluginInstallTransaction, + isPluginInstallCommitDeferred, + type PluginInstallTransaction, +} from "./install-transaction.js"; import { installPluginFromInstalledPackageDir, PLUGIN_INSTALL_ERROR_CODE, @@ -282,8 +292,24 @@ async function withGitStagingDir( async function replaceManagedGitRepo(params: { stagedRepoDir: string; persistentRepoDir: string; -}): Promise<{ ok: true } | { ok: false; error: string }> { + deferCommit?: boolean; +}): Promise<{ ok: true; transaction?: PluginInstallTransaction } | { ok: false; error: string }> { try { + if (params.deferCommit) { + const result = await installPackageDir( + requestDeferredPackageDirInstall({ + sourceDir: params.stagedRepoDir, + targetDir: params.persistentRepoDir, + mode: (await pathExists(params.persistentRepoDir)) ? "update" : "install", + timeoutMs: DEFAULT_GIT_TIMEOUT_MS, + copyErrorPrefix: "failed to replace managed git plugin repository", + hasDeps: false, + depsLogMessage: "", + }), + ); + const transaction = result.ok ? resolvePackageDirInstallTransaction(result) : undefined; + return result.ok ? { ok: true, ...(transaction ? { transaction } : {}) } : result; + } await replaceDirectoryAtomic({ stagedDir: params.stagedRepoDir, targetDir: params.persistentRepoDir, @@ -494,14 +520,17 @@ export async function installPluginFromGitSpec( if (!result.ok) { return result; } + let transaction: PluginInstallTransaction | undefined; if (!params.dryRun) { const replaceResult = await replaceManagedGitRepo({ stagedRepoDir: repoDir, persistentRepoDir, + deferCommit: isPluginInstallCommitDeferred(params), }); if (!replaceResult.ok) { return replaceResult; } + transaction = replaceResult.transaction; emitPluginInstallSecurityEvent({ pluginId: result.pluginId, mode: effectiveMode, @@ -512,7 +541,7 @@ export async function installPluginFromGitSpec( }); } - return { + const installed = { ...result, targetDir: params.dryRun ? result.targetDir : persistentRepoDir, git: { @@ -522,5 +551,6 @@ export async function installPluginFromGitSpec( resolvedAt: new Date().toISOString(), }, }; + return transaction ? attachPluginInstallTransaction(installed, transaction) : installed; }); } diff --git a/src/plugins/install-managed-npm.ts b/src/plugins/install-managed-npm.ts index 58dd0185a64b..05796d386708 100644 --- a/src/plugins/install-managed-npm.ts +++ b/src/plugins/install-managed-npm.ts @@ -59,6 +59,10 @@ import { runInstallSourceScan, sourceFamilyForInstallPolicySource, } from "./install-shared.js"; +import { + attachPluginInstallTransaction, + isPluginInstallCommitDeferred, +} from "./install-transaction.js"; import type { InstallPluginResult, PluginInstallLogger, @@ -184,6 +188,7 @@ export async function installPluginFromManagedNpmRoot( quarantine: ManagedNpmProjectQuarantine; } | undefined; + let deferredTransaction = false; try { rollbackSnapshot = await createManagedNpmPluginInstallRollbackSnapshot({ npmRoot }); } catch (error) { @@ -615,16 +620,67 @@ export async function installPluginFromManagedNpmRoot( return dependencyResult; } preparedDependency = dependencyResult; - return await runManagedNpmInstall(preparedDependency); + const result = await runManagedNpmInstall(preparedDependency); + if (!result.ok || !isPluginInstallCommitDeferred(params)) { + return result; + } + deferredTransaction = true; + let settled = false; + const cleanup = async () => { + await cleanupManagedNpmRootPreparedDependency({ + packageName: params.packageName, + preparedDependency, + logger, + }); + await cleanupManagedNpmPluginInstallRollbackSnapshot({ + snapshot: rollbackSnapshot, + logger, + }); + }; + return attachPluginInstallTransaction( + { ...result }, + { + async commit() { + if (settled) { + return; + } + settled = true; + await cleanup(); + }, + async rollback() { + if (settled) { + return; + } + settled = true; + await rollbackManagedNpmPluginInstall({ + npmRoot, + packageName: params.packageName, + targetDir: installRoot, + timeoutMs, + logger, + peerDependencySnapshot: rollbackPeerDependencySnapshot, + snapshot: recovery ? undefined : rollbackSnapshot, + }); + await rollbackManagedNpmRootPreparedDependency({ + packageName: params.packageName, + preparedDependency: dependencyResult, + logger, + }); + await cleanup(); + }, + }, + ); } finally { - await cleanupManagedNpmRootPreparedDependency({ - packageName: params.packageName, - preparedDependency, - logger, - }); - await cleanupManagedNpmPluginInstallRollbackSnapshot({ - snapshot: rollbackSnapshot, - logger, - }); + if (!deferredTransaction) { + await cleanupManagedNpmRootPreparedDependency({ + packageName: params.packageName, + preparedDependency, + logger, + }); + await cleanupManagedNpmPluginInstallRollbackSnapshot({ + snapshot: rollbackSnapshot, + logger, + }); + } } } diff --git a/src/plugins/install-npm.ts b/src/plugins/install-npm.ts index 67d9d93c58f7..16b109a57934 100644 --- a/src/plugins/install-npm.ts +++ b/src/plugins/install-npm.ts @@ -35,6 +35,7 @@ import { resolveEffectiveInstallMode, runInstallSourceScan, } from "./install-shared.js"; +import { copyPluginInstallTransactionRequest } from "./install-transaction.js"; import { PLUGIN_INSTALL_ERROR_CODE, type InstallPluginResult, @@ -250,34 +251,36 @@ export async function installPluginFromNpmSpec( await fs.rm(policyTempDir, { recursive: true, force: true }); } - const result = await installPluginFromManagedNpmRoot({ - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, - config: params.config, - packageName: parsedSpec.name, - dependencySpec: resolveManagedNpmRootDependencySpec({ - parsedSpec, - resolution: npmResolution, + const result = await installPluginFromManagedNpmRoot( + copyPluginInstallTransactionRequest(params, { + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, + config: params.config, + packageName: parsedSpec.name, + dependencySpec: resolveManagedNpmRootDependencySpec({ + parsedSpec, + resolution: npmResolution, + }), + displaySpec: spec, + installPolicyRequest: { + kind: "plugin-npm", + requestedSpecifier: spec, + source: npmInstallPolicySource, + }, + extensionsDir: params.extensionsDir, + npmDir: params.npmDir, + timeoutMs, + signal: params.signal, + logger, + mode, + dryRun, + skipPolicyPreflight: true, + expectedPluginId, + expectedReplacementPluginId: params.expectedReplacementPluginId, + npmResolution, + ...(driftResult.integrityDrift ? { integrityDrift: driftResult.integrityDrift } : {}), }), - displaySpec: spec, - installPolicyRequest: { - kind: "plugin-npm", - requestedSpecifier: spec, - source: npmInstallPolicySource, - }, - extensionsDir: params.extensionsDir, - npmDir: params.npmDir, - timeoutMs, - signal: params.signal, - logger, - mode, - dryRun, - skipPolicyPreflight: true, - expectedPluginId, - expectedReplacementPluginId: params.expectedReplacementPluginId, - npmResolution, - ...(driftResult.integrityDrift ? { integrityDrift: driftResult.integrityDrift } : {}), - }); + ); emitSuccessfulPluginInstallSecurityEvent(result, { dryRun, mode: policyMode, diff --git a/src/plugins/install-package.ts b/src/plugins/install-package.ts index 6000de33efa0..8e1bc09308bd 100644 --- a/src/plugins/install-package.ts +++ b/src/plugins/install-package.ts @@ -23,6 +23,7 @@ import { validateOpenClawPackageInstallCompatibility, type PreparedInstallTarget, } from "./install-shared.js"; +import { copyPluginInstallTransactionRequest } from "./install-transaction.js"; import { PLUGIN_INSTALL_ERROR_CODE, type InstallPluginResult, @@ -44,7 +45,7 @@ const PLUGIN_ARCHIVE_ROOT_MARKERS = [ function pickPackageInstallCommonParams( params: InternalPackageInstallCommonParams, ): InternalPackageInstallCommonParams { - return { + return copyPluginInstallTransactionRequest(params, { config: params.config, dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, @@ -59,7 +60,7 @@ function pickPackageInstallCommonParams( allowSourceTypeScriptEntries: params.allowSourceTypeScriptEntries, installPolicyRequest: params.installPolicyRequest, onEffectiveMode: params.onEffectiveMode, - }; + }); } function installPolicyRequestForPath( @@ -176,22 +177,24 @@ async function installBundleFromSourceDir( return scanResult; } - const installed = await installPluginDirectoryIntoExtensions({ - sourceDir: params.sourceDir, - pluginId, - manifestName: manifestRes.manifest.name, - version: manifestRes.manifest.version, - extensions: [], - targetDir: targetResult.target.targetPath, - extensionsDir: params.extensionsDir, - logger, - timeoutMs, - mode: targetResult.target.effectiveMode, - dryRun, - copyErrorPrefix: "failed to copy plugin bundle", - hasDeps: false, - depsLogMessage: "", - }); + const installed = await installPluginDirectoryIntoExtensions( + copyPluginInstallTransactionRequest(params, { + sourceDir: params.sourceDir, + pluginId, + manifestName: manifestRes.manifest.name, + version: manifestRes.manifest.version, + extensions: [], + targetDir: targetResult.target.targetPath, + extensionsDir: params.extensionsDir, + logger, + timeoutMs, + mode: targetResult.target.effectiveMode, + dryRun, + copyErrorPrefix: "failed to copy plugin bundle", + hasDeps: false, + depsLogMessage: "", + }), + ); return installed.ok ? { ...installed, @@ -310,42 +313,44 @@ async function installPluginFromPackageDir( !hasBundleManifest && params.installPolicyRequest?.kind === "plugin-archive"; - return await installPluginDirectoryIntoExtensions({ - sourceDir: params.packageDir, - pluginId: plugin.pluginId, - manifestName: plugin.manifestName, - version: plugin.version, - extensions: plugin.extensions, - setup: plugin.setup, - targetDir: preparedTarget.targetPath, - extensionsDir: params.extensionsDir, - logger, - timeoutMs, - mode: effectiveMode, - dryRun, - copyErrorPrefix: "failed to copy plugin", - hasDeps: shouldInstallRuntimeDeps, - sourceHardlinks: shouldInstallRuntimeDeps ? "package-manager" : "reject", - depsLogMessage: "Installing plugin dependencies…", - nameEncoder: encodePluginInstallDirName, - afterInstall: async (installedDir) => { - return await scanAndLinkInstalledPackage({ - runtime, - installedDir, - pluginId: plugin.pluginId, - peerDependencies: plugin.peerDependencies, - trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, - config: params.config, - mode: effectiveMode, - ...(params.installPolicyRequest?.kind - ? { requestKind: params.installPolicyRequest.kind } - : {}), - requestedSpecifier: params.installPolicyRequest?.requestedSpecifier, - source: params.installPolicyRequest?.source, - logger, - }); - }, - }); + return await installPluginDirectoryIntoExtensions( + copyPluginInstallTransactionRequest(params, { + sourceDir: params.packageDir, + pluginId: plugin.pluginId, + manifestName: plugin.manifestName, + version: plugin.version, + extensions: plugin.extensions, + setup: plugin.setup, + targetDir: preparedTarget.targetPath, + extensionsDir: params.extensionsDir, + logger, + timeoutMs, + mode: effectiveMode, + dryRun, + copyErrorPrefix: "failed to copy plugin", + hasDeps: shouldInstallRuntimeDeps, + sourceHardlinks: shouldInstallRuntimeDeps ? "package-manager" : "reject", + depsLogMessage: "Installing plugin dependencies…", + nameEncoder: encodePluginInstallDirName, + afterInstall: async (installedDir) => { + return await scanAndLinkInstalledPackage({ + runtime, + installedDir, + pluginId: plugin.pluginId, + peerDependencies: plugin.peerDependencies, + trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, + config: params.config, + mode: effectiveMode, + ...(params.installPolicyRequest?.kind + ? { requestKind: params.installPolicyRequest.kind } + : {}), + requestedSpecifier: params.installPolicyRequest?.requestedSpecifier, + source: params.installPolicyRequest?.source, + logger, + }); + }, + }), + ); } export async function installPluginFromArchive( @@ -378,22 +383,24 @@ export async function installPluginFromArchive( onExtracted: async (sourceDir) => await installPluginFromSourceDir({ sourceDir, - ...pickPackageInstallCommonParams({ - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - extensionsDir: params.extensionsDir, - timeoutMs, - logger, - mode, - dryRun: params.dryRun, - config: params.config, - expectedPluginId: params.expectedPluginId, - trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, - requirePluginManifest: true, - installPolicyRequest, - onEffectiveMode: (resolvedMode) => { - effectiveMode = resolvedMode; - }, - }), + ...pickPackageInstallCommonParams( + copyPluginInstallTransactionRequest(params, { + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + extensionsDir: params.extensionsDir, + timeoutMs, + logger, + mode, + dryRun: params.dryRun, + config: params.config, + expectedPluginId: params.expectedPluginId, + trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, + requirePluginManifest: true, + installPolicyRequest, + onEffectiveMode: (resolvedMode) => { + effectiveMode = resolvedMode; + }, + }), + ), }), }); emitSuccessfulPluginInstallSecurityEvent(result, { diff --git a/src/plugins/install-persistence.test.ts b/src/plugins/install-persistence.test.ts index 446c4e54ac3d..6d1376195766 100644 --- a/src/plugins/install-persistence.test.ts +++ b/src/plugins/install-persistence.test.ts @@ -22,6 +22,7 @@ import { } from "../cli/plugins-cli-test-helpers.js"; import type { OpenClawConfig } from "../config/config.js"; import { hasRetainedManagedNpmInstallMarker } from "./managed-npm-retention.js"; +import { recordPluginManifestInstallOwner } from "./manifest-install-owner.js"; import type { PluginManifestRecord } from "./manifest-registry.js"; function requireMockCallArg( @@ -45,19 +46,22 @@ function createManifestRecord( overrides: Partial = {}, ): PluginManifestRecord { const rootDir = path.join(os.tmpdir(), "openclaw-plugin-fixtures", id); - return { + return recordPluginManifestInstallOwner( + { + id, + channels: [], + providers: [], + cliBackends: [], + skills: [], + hooks: [], + origin: "config", + rootDir, + source: path.join(rootDir, "index.ts"), + manifestPath: path.join(rootDir, "openclaw.plugin.json"), + ...overrides, + }, id, - channels: [], - providers: [], - cliBackends: [], - skills: [], - hooks: [], - origin: "config", - rootDir, - source: path.join(rootDir, "index.ts"), - manifestPath: path.join(rootDir, "openclaw.plugin.json"), - ...overrides, - }; + ); } const installWriteOptions = { @@ -105,7 +109,7 @@ describe("persistPluginInstall", () => { const [cfg, pluginId] = args as [OpenClawConfig, string]; expect(pluginId).toBe("alpha"); expect(cfg.plugins?.allow).toEqual(["memory-core", "alpha"]); - return { config: enabledConfig }; + return { config: enabledConfig, enabled: true }; }); const next = await persistPluginInstall({ @@ -182,7 +186,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); clearPluginRegistryLoadCacheMock.mockImplementation(() => { throw new Error("cache unavailable"); }); @@ -220,7 +224,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); setInstalledPluginIndexInstallRecords({ codex: { source: "clawhub", @@ -266,21 +270,23 @@ describe("persistPluginInstall", () => { }, }); - expect(planPluginUninstallMock).toHaveBeenCalledWith({ - config: { - plugins: { - installs: { - codex: { - source: "clawhub", - spec: "clawhub:@openclaw/codex", - installPath: "/tmp/openclaw/extensions/codex", + expect(planPluginUninstallMock).toHaveBeenCalledWith( + expect.objectContaining({ + config: { + plugins: { + installs: { + codex: { + source: "clawhub", + spec: "clawhub:@openclaw/codex", + installPath: "/tmp/openclaw/extensions/codex", + }, }, }, }, - }, - pluginId: "codex", - deleteFiles: true, - }); + pluginId: "codex", + deleteFiles: true, + }), + ); expect(applyPluginUninstallDirectoryRemovalMock).toHaveBeenCalledWith({ target: "/tmp/openclaw/extensions/codex", }); @@ -308,7 +314,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); setInstalledPluginIndexInstallRecords({ codex: { source: "npm", @@ -349,7 +355,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-plugin-persist-")); const previousProjectRoot = path.join(tempRoot, "npm", "projects", "codex-v1"); const previousInstallPath = path.join( @@ -415,21 +421,23 @@ describe("persistPluginInstall", () => { }, }); - expect(planPluginUninstallMock).toHaveBeenCalledWith({ - config: { - plugins: { - installs: { - codex: { - source: "npm", - spec: "@openclaw/codex@1.0.0", - installPath: previousInstallPath, + expect(planPluginUninstallMock).toHaveBeenCalledWith( + expect.objectContaining({ + config: { + plugins: { + installs: { + codex: { + source: "npm", + spec: "@openclaw/codex@1.0.0", + installPath: previousInstallPath, + }, }, }, }, - }, - pluginId: "codex", - deleteFiles: true, - }); + pluginId: "codex", + deleteFiles: true, + }), + ); expect(applyPluginUninstallDirectoryRemovalMock).not.toHaveBeenCalled(); expect(hasRetainedManagedNpmInstallMarker(previousInstallPath)).toBe(true); } finally { @@ -451,7 +459,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); buildPluginSnapshotReportMock.mockReturnValue({ plugins: [ { @@ -510,7 +518,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); buildPluginSnapshotReportMock.mockReturnValue({ plugins: [ { @@ -554,7 +562,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); refreshPluginRegistryMock.mockRejectedValueOnce(new Error("registry unavailable")); const next = await persistPluginInstall({ @@ -591,7 +599,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); const next = await persistPluginInstall({ snapshot: { @@ -632,7 +640,7 @@ describe("persistPluginInstall", () => { const [cfg, pluginId] = args as [OpenClawConfig, string]; expect(pluginId).toBe("alpha"); expect(cfg.plugins?.deny).toEqual(["other"]); - return { config: enabledConfig }; + return { config: enabledConfig, enabled: true }; }); const next = await persistPluginInstall({ @@ -669,7 +677,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); loadPluginManifestRegistryMock.mockReturnValue({ plugins: [createManifestRecord("legacy-memory")], diagnostics: [], @@ -747,7 +755,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); loadPluginManifestRegistryMock.mockReturnValue({ plugins: [createManifestRecord("memory-b", { kind: "memory" })], diagnostics: [], @@ -814,7 +822,7 @@ describe("persistPluginInstall", () => { }, }, } as OpenClawConfig; - enablePluginInConfigMock.mockReturnValue({ config: enabledConfig }); + enablePluginInConfigMock.mockReturnValue({ config: enabledConfig, enabled: true }); loadPluginManifestRegistryMock.mockReturnValue({ plugins: [createManifestRecord("plain")], diagnostics: [], @@ -868,15 +876,18 @@ describe("persistPluginInstall", () => { } as OpenClawConfig; loadPluginManifestRegistryMock.mockReturnValue({ plugins: [ - { - id: "needs-config", - manifestPath: "/tmp/needs-config/openclaw.plugin.json", - configSchema: { - type: "object", - required: ["token"], - properties: { token: { type: "string" } }, + recordPluginManifestInstallOwner( + { + id: "needs-config", + manifestPath: "/tmp/needs-config/openclaw.plugin.json", + configSchema: { + type: "object", + required: ["token"], + properties: { token: { type: "string" } }, + }, }, - }, + "needs-config", + ), ], diagnostics: [], }); @@ -934,15 +945,18 @@ describe("persistPluginInstall", () => { } as OpenClawConfig; loadPluginManifestRegistryMock.mockReturnValue({ plugins: [ - { - id: "needs-config", - manifestPath: "/tmp/needs-config/openclaw.plugin.json", - configSchema: { - type: "object", - required: ["token"], - properties: { token: { type: "string" } }, + recordPluginManifestInstallOwner( + { + id: "needs-config", + manifestPath: "/tmp/needs-config/openclaw.plugin.json", + configSchema: { + type: "object", + required: ["token"], + properties: { token: { type: "string" } }, + }, }, - }, + "needs-config", + ), ], diagnostics: [], }); diff --git a/src/plugins/install-persistence.ts b/src/plugins/install-persistence.ts index b94978fe6c91..a05c9d26b404 100644 --- a/src/plugins/install-persistence.ts +++ b/src/plugins/install-persistence.ts @@ -16,6 +16,11 @@ import { isPathInside } from "../infra/path-guards.js"; import { defaultRuntime, type RuntimeEnv } from "../runtime.js"; import { resolveUserPath, shortenHomePath } from "../utils.js"; import { parseJsonWithJson5Fallback } from "../utils/parse-json-compat.js"; +import { + isPluginCandidateInstallOwnerAmbiguous, + resolvePluginCandidateInstallOwner, +} from "./candidate-install-owner.js"; +import { discoverOpenClawPlugins } from "./discovery.js"; import { enablePluginInConfig } from "./enable.js"; import { commitPluginInstallRecordsWithConfig } from "./install-record-commit.js"; import type { PluginInstallLogger } from "./install-types.js"; @@ -25,12 +30,18 @@ import { withoutPluginInstallRecords, } from "./installed-plugin-index-records.js"; import { reconcileNpmPluginLoadPath, type PluginInstallUpdate } from "./installs.js"; -import { loadPluginManifestRegistryCore } from "./manifest-registry.js"; +import { + isPluginManifestInstallOwnerAmbiguous, + resolvePluginManifestInstallOwner, +} from "./manifest-install-owner.js"; +import { loadPluginManifestRegistryCore, type PluginManifestRecord } from "./manifest-registry.js"; +import { safeRealpathSync } from "./path-safety.js"; import { tracePluginLifecyclePhaseAsync } from "./plugin-lifecycle-trace.js"; import { refreshPluginRegistryAfterConfigMutation } from "./registry-refresh.js"; import { validateJsonSchemaValue } from "./schema-validator.js"; import { applySlotSelectionForPlugin } from "./slot-selection.js"; import { buildPluginSnapshotReport } from "./status.js"; +import { recordPluginPackageUninstallPlan } from "./uninstall-package-plan.js"; import { applyPluginUninstallDirectoryRemoval, planPluginUninstall, @@ -386,17 +397,22 @@ function resolveReplacedManagedInstallRemoval(params: { ) { return null; } - const plan = planPluginUninstall({ - config: { - plugins: { - installs: { - [params.pluginId]: params.previousInstall, - }, + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: { + plugins: { + installs: { + [params.pluginId]: params.previousInstall, + }, + }, + } as OpenClawConfig, + pluginId: params.pluginId, + deleteFiles: true, }, - } as OpenClawConfig, - pluginId: params.pluginId, - deleteFiles: true, - }); + { runtimePluginIds: [] }, + ), + ); if (!plan.ok || !plan.directoryRemoval) { return null; } @@ -435,12 +451,9 @@ type PluginConfigEnablement = function resolvePluginConfigEnablement(params: { config: OpenClawConfig; pluginId: string; - installRecords: Record; + manifest?: PluginManifestRecord; }): PluginConfigEnablement { - const manifest = loadPluginManifestRegistryCore({ - config: params.config, - installRecords: params.installRecords, - }).plugins.find((plugin) => plugin.id === params.pluginId); + const manifest = params.manifest; if (!manifest?.configSchema) { return { mode: "ready" }; } @@ -501,41 +514,112 @@ export async function persistPluginInstall(params: { previousInstall, nextInstall: params.install, }); - const configEnablement = resolvePluginConfigEnablement({ - config: reconciledConfig, - pluginId: params.pluginId, - installRecords: nextInstallRecords, + const installedDiscovery = discoverOpenClawPlugins({ installRecords: nextInstallRecords }); + const realpathCache = new Map(); + const targetPathKeys = new Set( + [params.install.installPath, params.install.sourcePath] + .filter((candidate): candidate is string => Boolean(candidate?.trim())) + .map((candidate) => { + const resolved = resolveUserPath(candidate, process.env); + return safeRealpathSync(resolved, realpathCache) ?? path.resolve(resolved); + }), + ); + const installedCandidates = installedDiscovery.candidates.filter((candidate) => { + if (resolvePluginCandidateInstallOwner(candidate) === params.pluginId) { + return true; + } + const candidatePath = candidate.packageDir ?? candidate.rootDir; + const resolved = resolveUserPath(candidatePath, process.env); + const pathKey = safeRealpathSync(resolved, realpathCache) ?? path.resolve(resolved); + return targetPathKeys.has(pathKey); }); - if (configEnablement.mode === "invalid") { + if (installedCandidates.some(isPluginCandidateInstallOwnerAmbiguous)) { throw new Error( - `Plugin "${params.pluginId}" has invalid configured settings: ${configEnablement.error}. Fix plugins.entries.${params.pluginId}.config, then rerun the install.`, + `Plugin package "${params.pluginId}" has ambiguous install ownership. Refresh the plugin registry or reinstall the package before retrying.`, ); } - const shouldEnable = params.enable !== false && configEnablement.mode === "ready"; - const configBase = - params.enable === false || configEnablement.mode === "ready" - ? reconciledConfig - : prepareConfigForDisabledInstall(reconciledConfig, params.pluginId); - const installConfig = - params.enable === false - ? configBase - : removeInstalledPluginFromDenylist( - addInstalledPluginToAllowlist(configBase, params.pluginId), - params.pluginId, - ); - let next = shouldEnable - ? enablePluginInConfig(installConfig, params.pluginId, { - updateChannelConfig: false, - }).config - : installConfig; - const slotResult = shouldEnable - ? await tracePluginLifecyclePhaseAsync( - "slot selection", - async () => applySlotSelectionForPlugin(next, params.pluginId), - { command: "install", pluginId: params.pluginId }, - ) - : { config: next, warnings: [] }; - next = withoutPluginInstallRecords(slotResult.config); + const installedRegistry = loadPluginManifestRegistryCore({ + config: reconciledConfig, + candidates: installedCandidates, + diagnostics: installedDiscovery.diagnostics, + installRecords: nextInstallRecords, + }); + if (installedRegistry.plugins.some(isPluginManifestInstallOwnerAmbiguous)) { + throw new Error( + `Plugin package "${params.pluginId}" has ambiguous install ownership. Refresh the plugin registry or reinstall the package before retrying.`, + ); + } + const manifests = installedRegistry.plugins.filter( + (plugin) => resolvePluginManifestInstallOwner(plugin) === params.pluginId, + ); + if (manifests.length === 0) { + throw new Error( + `Plugin package "${params.pluginId}" has no authoritative runtime child list. Refresh the plugin registry, then reinstall the package or run openclaw doctor before retrying.`, + ); + } + const ownedPluginIds = manifests.map((plugin) => plugin.id).toSorted(); + const manifestByPluginId = new Map(manifests.map((plugin) => [plugin.id, plugin])); + const enablementByPluginId = new Map( + ownedPluginIds.map((pluginId) => [ + pluginId, + resolvePluginConfigEnablement({ + config: reconciledConfig, + pluginId, + manifest: manifestByPluginId.get(pluginId), + }), + ]), + ); + for (const [pluginId, configEnablement] of enablementByPluginId) { + if (configEnablement.mode === "invalid") { + throw new Error( + `Plugin "${pluginId}" has invalid configured settings: ${configEnablement.error}. Fix plugins.entries.${pluginId}.config, then rerun the install.`, + ); + } + } + + let next = reconciledConfig; + const enabledPluginIds: string[] = []; + const preserveExistingPolicy = previousInstall !== undefined; + for (const pluginId of ownedPluginIds) { + const configEnablement = enablementByPluginId.get(pluginId) ?? { mode: "ready" as const }; + const explicitlyDisabled = reconciledConfig.plugins?.entries?.[pluginId]?.enabled === false; + const existingAllow = reconciledConfig.plugins?.allow ?? []; + const blockedByExistingPolicy = + preserveExistingPolicy && + ((reconciledConfig.plugins?.deny ?? []).includes(pluginId) || + (existingAllow.length > 0 && !existingAllow.includes(pluginId))); + if (configEnablement.mode === "missing") { + next = prepareConfigForDisabledInstall(next, pluginId); + } + if (params.enable === false) { + continue; + } + if (!preserveExistingPolicy) { + next = removeInstalledPluginFromDenylist( + addInstalledPluginToAllowlist(next, pluginId), + pluginId, + ); + } + if (configEnablement.mode !== "ready" || explicitlyDisabled || blockedByExistingPolicy) { + continue; + } + const enabled = enablePluginInConfig(next, pluginId, { updateChannelConfig: false }); + next = enabled.config; + if (enabled.enabled) { + enabledPluginIds.push(pluginId); + } + } + const slotWarnings: string[] = []; + for (const pluginId of enabledPluginIds) { + const slotResult = await tracePluginLifecyclePhaseAsync( + "slot selection", + async () => applySlotSelectionForPlugin(next, pluginId), + { command: "install", pluginId }, + ); + next = slotResult.config; + slotWarnings.push(...slotResult.warnings); + } + next = withoutPluginInstallRecords(next); await tracePluginLifecyclePhaseAsync( "config mutation", () => @@ -585,12 +669,17 @@ export async function persistPluginInstall(params: { ), }, }); - for (const warning of slotResult.warnings) { + for (const warning of slotWarnings) { warn(warning, warning); } + const configurationRequiredPluginIds = [...enablementByPluginId] + .filter(([, state]) => state.mode === "missing") + .map(([pluginId]) => pluginId); const configWarning = - params.enable !== false && configEnablement.mode === "missing" - ? `Installed plugin "${params.pluginId}" without enabling it because it requires configuration first. Configure it, then run \`openclaw plugins enable ${params.pluginId}\`.` + params.enable !== false && configurationRequiredPluginIds.length > 0 + ? configurationRequiredPluginIds.length === 1 + ? `Installed plugin "${configurationRequiredPluginIds[0]}" without enabling it because it requires configuration first. Configure it, then run \`openclaw plugins enable ${configurationRequiredPluginIds[0]}\`.` + : `Installed plugin entries ${configurationRequiredPluginIds.join(", ")} without enabling them because they require configuration first. Configure each entry, then run \`openclaw plugins enable \`.` : undefined; const warningMessage = [params.warningMessage, configWarning].filter(Boolean).join("\n"); if (warningMessage) { @@ -599,7 +688,12 @@ export async function persistPluginInstall(params: { configWarning ?? "Plugin installation reported a warning. Run `openclaw plugins doctor`.", ); } - runtime.log(params.successMessage ?? `Installed plugin: ${params.pluginId}`); + runtime.log( + params.successMessage ?? + (ownedPluginIds.length > 1 + ? `Installed plugin package ${params.pluginId}: ${ownedPluginIds.join(", ")}` + : `Installed plugin: ${params.pluginId}`), + ); logShadowedNpmInstallWarning({ config: next, pluginId: params.pluginId, diff --git a/src/plugins/install-record-commit.ts b/src/plugins/install-record-commit.ts index 8c68c8e50c0a..45d6cbc35862 100644 --- a/src/plugins/install-record-commit.ts +++ b/src/plugins/install-record-commit.ts @@ -41,6 +41,7 @@ import { resolveRetainedManagedNpmInstallMarkerPath, } from "./managed-npm-retention.js"; import { withPluginLifecycleLease } from "./plugin-lifecycle-lease.js"; +import { recordPluginPackageUninstallPlan } from "./uninstall-package-plan.js"; import { planPluginUninstall } from "./uninstall.js"; function mergeUnsetPaths( @@ -213,15 +214,20 @@ function resolveRetainedManagedNpmInstallMarkerTarget(params: { } const installs = createPluginInstallRecordMap(); setPluginInstallRecordMapEntry(installs, params.pluginId, params.previousRecord); - const plan = planPluginUninstall({ - config: { - plugins: { - installs, + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: { + plugins: { + installs, + }, + } as OpenClawConfig, + pluginId: params.pluginId, + deleteFiles: true, }, - } as OpenClawConfig, - pluginId: params.pluginId, - deleteFiles: true, - }); + { runtimePluginIds: [] }, + ), + ); if ( !plan.ok || !plan.directoryRemoval || diff --git a/src/plugins/install-shared.ts b/src/plugins/install-shared.ts index 4481f388e082..90fc644e4b69 100644 --- a/src/plugins/install-shared.ts +++ b/src/plugins/install-shared.ts @@ -1,9 +1,17 @@ import path from "node:path"; +import { + requestDeferredPackageDirInstall, + resolvePackageDirInstallTransaction, +} from "../infra/install-package-dir.js"; import type { InstallPolicySource } from "../security/install-policy.js"; import { createLazyImportLoader } from "../shared/lazy-promise.js"; import { resolveUserPath } from "../utils.js"; import { resolveDefaultPluginExtensionsDir } from "./install-paths.js"; import type { InstallSecurityScanResult } from "./install-security-scan.js"; +import { + attachPluginInstallTransaction, + isPluginInstallCommitDeferred, +} from "./install-transaction.js"; import { PLUGIN_INSTALL_ERROR_CODE, type InstallPluginResult, @@ -413,7 +421,7 @@ export async function installPluginDirectoryIntoExtensions(params: { }); } - const installRes = await runtime.installPackageDir({ + const packageInstallParams = { sourceDir: params.sourceDir, targetDir, mode: params.mode, @@ -424,7 +432,7 @@ export async function installPluginDirectoryIntoExtensions(params: { sourceHardlinks: params.sourceHardlinks ?? "reject", depsLogMessage: params.depsLogMessage, afterCopy: params.afterCopy, - afterInstall: async (installedDir) => { + afterInstall: async (installedDir: string) => { const postInstallResult = await params.afterInstall?.(installedDir); if (!postInstallResult) { return { ok: true as const }; @@ -435,7 +443,12 @@ export async function installPluginDirectoryIntoExtensions(params: { ...(postInstallResult.code ? { code: postInstallResult.code } : {}), }; }, - }); + }; + const installRes = await runtime.installPackageDir( + isPluginInstallCommitDeferred(params) + ? requestDeferredPackageDirInstall(packageInstallParams) + : packageInstallParams, + ); if (!installRes.ok) { return { ok: false, @@ -444,14 +457,18 @@ export async function installPluginDirectoryIntoExtensions(params: { }; } - return buildDirectoryInstallResult({ - pluginId: params.pluginId, - targetDir, - manifestName: params.manifestName, - version: params.version, - extensions: params.extensions, - setup: params.setup, - }); + const result = { + ...buildDirectoryInstallResult({ + pluginId: params.pluginId, + targetDir, + manifestName: params.manifestName, + version: params.version, + extensions: params.extensions, + setup: params.setup, + }), + }; + const transaction = resolvePackageDirInstallTransaction(installRes); + return transaction ? attachPluginInstallTransaction(result, transaction) : result; } async function resolvePluginInstallTarget(params: { diff --git a/src/plugins/install-transaction.ts b/src/plugins/install-transaction.ts new file mode 100644 index 000000000000..7846fac13f01 --- /dev/null +++ b/src/plugins/install-transaction.ts @@ -0,0 +1,112 @@ +export type PluginInstallTransaction = { + commit(): Promise; + rollback(): Promise; +}; + +const PLUGIN_INSTALL_TRANSACTION = Symbol.for("openclaw.pluginInstallTransaction"); +const PLUGIN_INSTALL_TRANSACTION_REQUEST = Symbol.for("openclaw.pluginInstallTransactionRequest"); +const PLUGIN_INSTALL_OWNER_MIGRATIONS = Symbol.for("openclaw.pluginInstallOwnerMigrations"); + +type PluginInstallTransactionRequest = { + deferCommit: true; + transactionSink?: PluginInstallTransaction[]; +}; + +export function attachPluginInstallTransaction( + result: T, + transaction: PluginInstallTransaction, +): T { + Object.defineProperty(result, PLUGIN_INSTALL_TRANSACTION, { + configurable: false, + enumerable: true, + value: transaction, + }); + return result; +} + +export function resolvePluginInstallTransaction( + result: object, +): PluginInstallTransaction | undefined { + return (result as { [PLUGIN_INSTALL_TRANSACTION]?: PluginInstallTransaction })[ + PLUGIN_INSTALL_TRANSACTION + ]; +} + +export function requestDeferredPluginInstall( + params: T, + transactionSink?: PluginInstallTransaction[], +): T { + Object.defineProperty(params, PLUGIN_INSTALL_TRANSACTION_REQUEST, { + configurable: false, + enumerable: true, + value: { + deferCommit: true, + ...(transactionSink ? { transactionSink } : {}), + } satisfies PluginInstallTransactionRequest, + }); + return params; +} + +export function copyPluginInstallTransactionRequest( + source: object, + target: T, +): T { + const request = resolvePluginInstallTransactionRequest(source); + return request ? requestDeferredPluginInstall(target, request.transactionSink) : target; +} + +function resolvePluginInstallTransactionRequest( + params: object, +): PluginInstallTransactionRequest | undefined { + return (params as { [PLUGIN_INSTALL_TRANSACTION_REQUEST]?: PluginInstallTransactionRequest })[ + PLUGIN_INSTALL_TRANSACTION_REQUEST + ]; +} + +export function isPluginInstallCommitDeferred(params: object): boolean { + return resolvePluginInstallTransactionRequest(params)?.deferCommit === true; +} + +export function resolvePluginInstallTransactionSink( + params: object, +): PluginInstallTransaction[] | undefined { + return resolvePluginInstallTransactionRequest(params)?.transactionSink; +} + +export function attachPluginInstallOwnerMigrations( + result: T, + migrations: Readonly>, +): T { + Object.defineProperty(result, PLUGIN_INSTALL_OWNER_MIGRATIONS, { + configurable: false, + enumerable: true, + value: migrations, + }); + return result; +} + +export function resolvePluginInstallOwnerMigrations( + result: object, +): Readonly> | undefined { + return (result as { [PLUGIN_INSTALL_OWNER_MIGRATIONS]?: Readonly> })[ + PLUGIN_INSTALL_OWNER_MIGRATIONS + ]; +} + +export async function settlePluginInstallTransactions( + transactions: readonly PluginInstallTransaction[], + action: "commit" | "rollback", +): Promise { + const ordered = action === "rollback" ? transactions.toReversed() : transactions; + const errors: unknown[] = []; + for (const transaction of ordered) { + try { + await transaction[action](); + } catch (error) { + errors.push(error); + } + } + if (errors.length > 0) { + throw new AggregateError(errors, `Plugin install transaction ${action} failed`); + } +} diff --git a/src/plugins/installed-plugin-index-install-owner.ts b/src/plugins/installed-plugin-index-install-owner.ts new file mode 100644 index 000000000000..09a3525385fb --- /dev/null +++ b/src/plugins/installed-plugin-index-install-owner.ts @@ -0,0 +1,43 @@ +type InstalledPluginIndexInstallOwner = { installOwner?: string; ambiguous?: true }; +type InstalledPluginIndexRecordWithOwner = { + installOwner?: string; + installOwnerAmbiguous?: true; +}; + +export function recordInstalledPluginIndexInstallOwner( + record: T, + installOwner: string | undefined, + ambiguous = false, +): T { + if (!installOwner && !ambiguous) { + return record; + } + const ownedRecord = record as T & InstalledPluginIndexRecordWithOwner; + if (ambiguous) { + delete ownedRecord.installOwner; + ownedRecord.installOwnerAmbiguous = true; + } else { + ownedRecord.installOwner = installOwner; + delete ownedRecord.installOwnerAmbiguous; + } + return record; +} + +function readInstalledPluginIndexInstallOwner( + record: object, +): InstalledPluginIndexInstallOwner | undefined { + const ownedRecord = record as InstalledPluginIndexRecordWithOwner; + return ownedRecord.installOwnerAmbiguous + ? { ambiguous: true } + : ownedRecord.installOwner + ? { installOwner: ownedRecord.installOwner } + : undefined; +} + +export function resolveInstalledPluginIndexInstallOwner(record: object): string | undefined { + return readInstalledPluginIndexInstallOwner(record)?.installOwner; +} + +export function isInstalledPluginIndexInstallOwnerAmbiguous(record: object): boolean { + return readInstalledPluginIndexInstallOwner(record)?.ambiguous === true; +} diff --git a/src/plugins/installed-plugin-index-invalidation.ts b/src/plugins/installed-plugin-index-invalidation.ts index 31dea4063700..562bcbc0395c 100644 --- a/src/plugins/installed-plugin-index-invalidation.ts +++ b/src/plugins/installed-plugin-index-invalidation.ts @@ -1,6 +1,10 @@ // Invalidates installed plugin index entries after activation metadata changes. import { hasConfigPathActivationMetadataMigration } from "./installed-plugin-index-config-path-scope.js"; import { hashJson } from "./installed-plugin-index-hash.js"; +import { + isInstalledPluginIndexInstallOwnerAmbiguous, + resolveInstalledPluginIndexInstallOwner, +} from "./installed-plugin-index-install-owner.js"; import type { InstalledPluginIndex, InstalledPluginIndexRefreshReason, @@ -41,6 +45,10 @@ export function diffInstalledPluginIndexInvalidationReasons( if ( previousPlugin.rootDir !== currentPlugin.rootDir || previousPlugin.manifestPath !== currentPlugin.manifestPath || + resolveInstalledPluginIndexInstallOwner(previousPlugin) !== + resolveInstalledPluginIndexInstallOwner(currentPlugin) || + isInstalledPluginIndexInstallOwnerAmbiguous(previousPlugin) !== + isInstalledPluginIndexInstallOwnerAmbiguous(currentPlugin) || previousPlugin.installRecordHash !== currentPlugin.installRecordHash ) { reasons.add("source-changed"); diff --git a/src/plugins/installed-plugin-index-record-builder.ts b/src/plugins/installed-plugin-index-record-builder.ts index 1d55be7160e4..2bb570724454 100644 --- a/src/plugins/installed-plugin-index-record-builder.ts +++ b/src/plugins/installed-plugin-index-record-builder.ts @@ -4,6 +4,10 @@ import { normalizeOptionalString as normalizeStringField } from "@openclaw/norma import { normalizeSortedUniqueStringEntries } from "@openclaw/normalization-core/string-normalization"; import { getPluginInstallRecordMapEntry } from "../config/plugin-install-record-map.js"; import type { OpenClawConfig } from "../config/types.js"; +import { + isPluginCandidateInstallOwnerAmbiguous, + resolvePluginCandidateInstallOwner, +} from "./candidate-install-owner.js"; import type { PluginCompatCode } from "./compat/registry.js"; import { normalizePluginsConfig, resolveEffectiveEnableState } from "./config-state.js"; import { isPluginEnabledByDefaultForPlatform } from "./default-enablement.js"; @@ -12,6 +16,7 @@ import { resolvePluginDoctorContractArtifactPath } from "./doctor-contract-artif import type { PluginInstallSourceInfo } from "./install-source-info.js"; import { describePluginInstallSource } from "./install-source-info.js"; import { hashJson, safeFileSignature, safeHashFile } from "./installed-plugin-index-hash.js"; +import { recordInstalledPluginIndexInstallOwner } from "./installed-plugin-index-install-owner.js"; import { hasOptionalMissingPluginManifestFile } from "./installed-plugin-index-manifest.js"; import type { InstalledPluginContributionInfo, @@ -20,6 +25,7 @@ import type { InstalledPluginPackageChannelInfo, InstalledPluginStartupInfo, } from "./installed-plugin-index-types.js"; +import { resolvePluginManifestInstallOwner } from "./manifest-install-owner.js"; import type { PluginManifestRecord, PluginManifestRegistry } from "./manifest-registry.js"; import type { PluginDiagnostic } from "./manifest-types.js"; import type { PluginPackageChannel } from "./manifest.js"; @@ -221,11 +227,11 @@ function resolveManifestHash(params: { function buildCandidateLookup( candidates: readonly PluginCandidate[], ): Map { - const byRootDir = new Map(); + const bySource = new Map(); for (const candidate of candidates) { - byRootDir.set(candidate.rootDir, candidate); + bySource.set(candidate.source, candidate); } - return byRootDir; + return bySource; } export function buildInstalledPluginIndexRecords(params: { @@ -235,13 +241,20 @@ export function buildInstalledPluginIndexRecords(params: { diagnostics: PluginDiagnostic[]; installRecords: Record; }): InstalledPluginIndexRecord[] { - const candidateByRootDir = buildCandidateLookup(params.candidates); + const candidateBySource = buildCandidateLookup(params.candidates); const normalizedConfig = normalizePluginsConfig(params.config?.plugins); const realpathCache = new Map(); return params.registry.plugins.map((record): InstalledPluginIndexRecord => { - const candidate = candidateByRootDir.get(record.rootDir); + const candidate = candidateBySource.get(record.source); const packageJsonPath = resolvePackageJsonPath(candidate, realpathCache); - const installRecord = getPluginInstallRecordMapEntry(params.installRecords, record.id); + const installOwner = + candidate && isPluginCandidateInstallOwnerAmbiguous(candidate) + ? undefined + : (resolvePluginManifestInstallOwner(record) ?? + (candidate ? resolvePluginCandidateInstallOwner(candidate) : undefined)); + const installRecord = installOwner + ? getPluginInstallRecordMapEntry(params.installRecords, installOwner) + : undefined; const packageInstall = describePackageInstallSource(candidate); const packageChannel = normalizePackageChannel( record.packageChannel ?? candidate?.packageManifest?.channel, @@ -330,6 +343,10 @@ export function buildInstalledPluginIndexRecords(params: { if (packageJson) { indexRecord.packageJson = packageJson; } - return indexRecord; + return recordInstalledPluginIndexInstallOwner( + indexRecord, + installOwner, + candidate ? isPluginCandidateInstallOwnerAmbiguous(candidate) : false, + ); }); } diff --git a/src/plugins/installed-plugin-index-store.ts b/src/plugins/installed-plugin-index-store.ts index 2d1a6339e6a3..0dd0204baec9 100644 --- a/src/plugins/installed-plugin-index-store.ts +++ b/src/plugins/installed-plugin-index-store.ts @@ -20,6 +20,11 @@ import { resolveCompatibilityHostVersion } from "../version.js"; import { normalizePluginsConfig, resolveEffectiveEnableState } from "./config-state.js"; import { isPluginEnabledByDefaultForPlatform } from "./default-enablement.js"; import { hashJson } from "./installed-plugin-index-hash.js"; +import { + isInstalledPluginIndexInstallOwnerAmbiguous, + recordInstalledPluginIndexInstallOwner, + resolveInstalledPluginIndexInstallOwner, +} from "./installed-plugin-index-install-owner.js"; import { resolveCompatRegistryVersion } from "./installed-plugin-index-policy.js"; import { clearLoadInstalledPluginIndexInstallRecordsCache } from "./installed-plugin-index-record-cache.js"; import { @@ -42,6 +47,7 @@ import { type LoadInstalledPluginIndexParams, type RefreshInstalledPluginIndexParams, } from "./installed-plugin-index.js"; +import { hasMissingInstalledPluginOwnerMetadata } from "./installed-plugin-package-ownership.js"; import { clearPluginMetadataLifecycleCaches } from "./plugin-metadata-lifecycle.js"; export { resolveInstalledPluginIndexStorePath, @@ -98,6 +104,8 @@ const InstalledPluginFileSignatureSchema = z.object({ const InstalledPluginIndexRecordSchema = z.object({ pluginId: z.string(), + installOwner: z.string().optional(), + installOwnerAmbiguous: z.literal(true).optional(), packageName: z.string().optional(), packageVersion: z.string().optional(), installRecord: PluginInstallRecordSchema.optional(), @@ -159,8 +167,14 @@ const InstalledPluginIndexSchema = z.object({ export function parseInstalledPluginIndex(value: unknown): InstalledPluginIndex | null { const parsed = safeParseWithSchema(InstalledPluginIndexSchema, value) as - | (Omit & { + | (Omit & { installRecords?: unknown; + plugins: Array< + InstalledPluginIndex["plugins"][number] & { + installOwner?: string; + installOwnerAmbiguous?: true; + } + >; }) | null; if (!parsed) { @@ -182,7 +196,9 @@ export function parseInstalledPluginIndex(value: unknown): InstalledPluginIndex generatedAtMs: parsed.generatedAtMs, ...(parsed.refreshReason ? { refreshReason: parsed.refreshReason } : {}), installRecords, - plugins: parsed.plugins, + plugins: parsed.plugins.map(({ installOwner, installOwnerAmbiguous, ...plugin }) => + recordInstalledPluginIndexInstallOwner(plugin, installOwner, installOwnerAmbiguous === true), + ), diagnostics: parsed.diagnostics, }; } @@ -317,7 +333,18 @@ function writePersistedInstalledPluginIndexRow( generated_at_ms: index.generatedAtMs, refresh_reason: index.refreshReason ?? null, install_records_json: serializePluginInstallRecordMap(index.installRecords), - plugins_json: JSON.stringify(index.plugins), + plugins_json: JSON.stringify( + index.plugins.map((plugin) => { + const installOwner = resolveInstalledPluginIndexInstallOwner(plugin); + return { + ...plugin, + ...(installOwner ? { installOwner } : {}), + ...(isInstalledPluginIndexInstallOwnerAmbiguous(plugin) + ? { installOwnerAmbiguous: true } + : {}), + }; + }), + ), diagnostics_json: JSON.stringify(index.diagnostics), warning: index.warning ?? INSTALLED_PLUGIN_INDEX_WARNING, updated_at_ms: revision, @@ -488,7 +515,8 @@ function canRefreshPersistedPolicyState( persisted.hostContractVersion !== resolveCompatibilityHostVersion(env) || persisted.compatRegistryVersion !== resolveCompatRegistryVersion() || persisted.migrationVersion !== INSTALLED_PLUGIN_INDEX_MIGRATION_VERSION || - hasMissingConfigPathActivationMetadata(persisted) + hasMissingConfigPathActivationMetadata(persisted) || + hasMissingInstalledPluginOwnerMetadata(persisted, env) ) { return false; } diff --git a/src/plugins/installed-plugin-package-ownership.ts b/src/plugins/installed-plugin-package-ownership.ts new file mode 100644 index 000000000000..509cf7cb9d32 --- /dev/null +++ b/src/plugins/installed-plugin-package-ownership.ts @@ -0,0 +1,159 @@ +import path from "node:path"; +import { resolveUserPath } from "../utils.js"; +import { + isInstalledPluginIndexInstallOwnerAmbiguous, + resolveInstalledPluginIndexInstallOwner, +} from "./installed-plugin-index-install-owner.js"; +import type { + InstalledPluginIndex, + InstalledPluginInstallRecordInfo, +} from "./installed-plugin-index-types.js"; +import { safeRealpathSync } from "./path-safety.js"; + +function collectDuplicateInstallRecordOwners( + index: InstalledPluginIndex, + env: NodeJS.ProcessEnv, +): Set { + const ownersByPath = new Map(); + const duplicateOwners = new Set(); + const realpathCache = new Map(); + for (const [installOwner, record] of Object.entries(index.installRecords)) { + const rawPath = record.installPath?.trim() || record.sourcePath?.trim(); + if (!rawPath) { + continue; + } + const resolved = path.resolve(resolveUserPath(rawPath, env)); + const pathKey = safeRealpathSync(resolved, realpathCache) ?? resolved; + const existingOwner = ownersByPath.get(pathKey); + if (existingOwner && existingOwner !== installOwner) { + duplicateOwners.add(existingOwner); + duplicateOwners.add(installOwner); + } + ownersByPath.set(pathKey, installOwner); + } + return duplicateOwners; +} + +export type InstalledPluginPackageOwnership = { + installOwner: string; + installRecord: InstalledPluginInstallRecordInfo; + pluginIds: string[]; +}; + +type InstalledPluginPackageOwnershipResult = + | { ok: true; value: InstalledPluginPackageOwnership } + | { ok: false; error: string }; + +function ownershipError(pluginId: string, detail: string): InstalledPluginPackageOwnershipResult { + return { + ok: false, + error: + `Plugin "${pluginId}" ${detail}. ` + + "Refresh the plugin registry, then reinstall the package or run openclaw doctor before retrying.", + }; +} + +export function resolveInstalledPluginPackageOwnership( + index: InstalledPluginIndex, + pluginId: string, + env: NodeJS.ProcessEnv = process.env, +): InstalledPluginPackageOwnershipResult { + const target = index.plugins.find((entry) => entry.pluginId === pluginId); + if (target && isInstalledPluginIndexInstallOwnerAmbiguous(target)) { + return ownershipError(pluginId, "has ambiguous package ownership"); + } + const ownerFromTarget = target ? resolveInstalledPluginIndexInstallOwner(target) : undefined; + if (target && !ownerFromTarget) { + return ownershipError(pluginId, "has no authoritative package-owner metadata"); + } + + const ownerFromRecord = Object.hasOwn(index.installRecords, pluginId) ? pluginId : undefined; + const installOwner = ownerFromTarget ?? ownerFromRecord; + if (!installOwner) { + return ownershipError(pluginId, "is not associated with a tracked package install"); + } + if (ownerFromTarget && ownerFromRecord && ownerFromTarget !== ownerFromRecord) { + return ownershipError(pluginId, "matches conflicting package owners"); + } + const installRecord = index.installRecords[installOwner]; + if (!installRecord) { + return ownershipError(pluginId, `references missing package owner "${installOwner}"`); + } + if (collectDuplicateInstallRecordOwners(index, env).has(installOwner)) { + return ownershipError(pluginId, `shares package path ownership with "${installOwner}"`); + } + + const pluginIds = index.plugins + .filter( + (entry) => + resolveInstalledPluginIndexInstallOwner(entry) === installOwner && + !isInstalledPluginIndexInstallOwnerAmbiguous(entry), + ) + .map((entry) => entry.pluginId) + .toSorted(); + if (pluginIds.length === 0) { + return ownershipError( + pluginId, + `package owner "${installOwner}" has no authoritative runtime child list`, + ); + } + if (target && !pluginIds.includes(target.pluginId)) { + return ownershipError(pluginId, `does not belong to package owner "${installOwner}"`); + } + + const hasUnsafePackageEntry = index.plugins.some( + (entry) => + installRecordPathMatchesPluginRoot(installRecord, entry.rootDir, env) && + (isInstalledPluginIndexInstallOwnerAmbiguous(entry) || + resolveInstalledPluginIndexInstallOwner(entry) !== installOwner), + ); + if (hasUnsafePackageEntry) { + return ownershipError(pluginId, `package owner "${installOwner}" has conflicting child rows`); + } + return { ok: true, value: { installOwner, installRecord, pluginIds } }; +} + +function installRecordPathMatchesPluginRoot( + record: InstalledPluginInstallRecordInfo, + rootDir: string, + env: NodeJS.ProcessEnv, +): boolean { + const realpathCache = new Map(); + const resolvedRoot = + safeRealpathSync(path.resolve(rootDir), realpathCache) ?? path.resolve(rootDir); + return [record.installPath, record.sourcePath].some((candidate) => { + if (!candidate?.trim()) { + return false; + } + const candidatePath = path.resolve(resolveUserPath(candidate, env)); + const resolvedCandidate = safeRealpathSync(candidatePath, realpathCache) ?? candidatePath; + const relative = path.relative(resolvedCandidate, resolvedRoot); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); + }); +} + +export function hasMissingInstalledPluginOwnerMetadata( + index: InstalledPluginIndex, + env: NodeJS.ProcessEnv = process.env, +): boolean { + if (collectDuplicateInstallRecordOwners(index, env).size > 0) { + return true; + } + const installRecords = Object.entries(index.installRecords); + if ( + index.plugins.some( + (plugin) => + isInstalledPluginIndexInstallOwnerAmbiguous(plugin) || + (!resolveInstalledPluginIndexInstallOwner(plugin) && + installRecords.some(([, record]) => + installRecordPathMatchesPluginRoot(record, plugin.rootDir, env), + )), + ) + ) { + return true; + } + // An orphaned owner record (for example, package code removed out of band) is + // already closed by the lifecycle resolver. It must not make every unrelated + // config read attempt an impossible registry migration with no discoverable rows. + return false; +} diff --git a/src/plugins/loader-provenance.ts b/src/plugins/loader-provenance.ts index 4d901be90941..6de74309782f 100644 --- a/src/plugins/loader-provenance.ts +++ b/src/plugins/loader-provenance.ts @@ -3,6 +3,11 @@ import { normalizeTrimmedStringList } from "@openclaw/normalization-core/string- import { quoteCliArg } from "../cli/quote-cli-arg.js"; import type { PluginInstallRecord } from "../config/types.plugins.js"; import { resolveUserPath } from "../utils.js"; +import { + isPluginCandidateInstallOwnerAmbiguous, + resolvePluginCandidateInstallOwner, + resolvePluginInstallOwnerLookup, +} from "./candidate-install-owner.js"; import { isBundledPluginInsideDevSourceRoot } from "./dev-source-root.js"; import type { PluginCandidate } from "./discovery.js"; import { loadInstalledPluginIndexInstallRecordsSync } from "./installed-plugin-index-records.js"; @@ -142,17 +147,17 @@ function matchesExplicitInstallRule(params: { function resolveCandidateDuplicateRank(params: { candidate: PluginCandidate; - manifestBySource: Map; provenance: PluginProvenanceIndex; env: NodeJS.ProcessEnv; }): number { - const manifestRecord = params.manifestBySource.get(params.candidate.source); - const pluginId = manifestRecord?.id; + const installOwner = isPluginCandidateInstallOwnerAmbiguous(params.candidate) + ? undefined + : resolvePluginCandidateInstallOwner(params.candidate); const isExplicitInstall = params.candidate.origin === "global" && - pluginId !== undefined && + installOwner !== undefined && matchesExplicitInstallRule({ - pluginId, + pluginId: installOwner, source: params.candidate.source, index: params.provenance, env: params.env, @@ -199,13 +204,11 @@ export function compareDuplicateCandidateOrder(params: { return ( resolveCandidateDuplicateRank({ candidate: params.left, - manifestBySource: params.manifestBySource, provenance: params.provenance, env: params.env, }) - resolveCandidateDuplicateRank({ candidate: params.right, - manifestBySource: params.manifestBySource, provenance: params.provenance, env: params.env, }) @@ -301,9 +304,11 @@ export function warnAboutUntrackedLoadedPlugins(params: { if (allowSet.has(plugin.id)) { continue; } + const installOwner = resolvePluginInstallOwnerLookup(params)?.get(plugin.id); if ( + installOwner && isTrackedByProvenance({ - pluginId: plugin.id, + pluginId: installOwner, source: plugin.source, index: params.provenance, env: params.env, diff --git a/src/plugins/loader-runtime-load.ts b/src/plugins/loader-runtime-load.ts index dc30d34f6bbe..fbf85d6c6d05 100644 --- a/src/plugins/loader-runtime-load.ts +++ b/src/plugins/loader-runtime-load.ts @@ -1,5 +1,9 @@ import type { GatewayRequestHandler } from "../gateway/server-methods/types.js"; import { normalizeAgentToolResultMiddlewareRuntimeIds } from "./agent-tool-result-middleware.js"; +import { + recordPluginInstallOwnerLookup, + resolvePluginCandidateInstallOwner, +} from "./candidate-install-owner.js"; import { resolveEffectivePluginActivationState } from "./config-state.js"; import { isPluginEnabledByDefaultForPlatform } from "./default-enablement.js"; import { @@ -247,14 +251,25 @@ function loadOpenClawPluginsInternal( message: `memory slot plugin not found or not marked as memory: ${memorySlot}`, }); } - warnAboutUntrackedLoadedPlugins({ - registry, - provenance, - allowlist: context.normalized.allow, - emitWarning: context.shouldActivate, - logger, - env: context.env, - }); + warnAboutUntrackedLoadedPlugins( + recordPluginInstallOwnerLookup( + { + registry, + provenance, + allowlist: context.normalized.allow, + emitWarning: context.shouldActivate, + logger, + env: context.env, + }, + new Map( + orderedCandidates.flatMap((candidate) => { + const pluginId = manifestBySource.get(candidate.source)?.id; + const installOwner = resolvePluginCandidateInstallOwner(candidate); + return pluginId && installOwner ? [[pluginId, installOwner] as const] : []; + }), + ), + ), + ); maybeThrowOnPluginLoadError(registry, options.throwOnLoadError); if (context.shouldActivate && options.mode !== "validate") { const failedPlugins = registry.plugins.filter((plugin) => plugin.failedAt != null); diff --git a/src/plugins/loader-shared.test.ts b/src/plugins/loader-shared.test.ts index e0a35a25fa85..e17768ed450f 100644 --- a/src/plugins/loader-shared.test.ts +++ b/src/plugins/loader-shared.test.ts @@ -1,6 +1,12 @@ import { describe, expect, it } from "vitest"; +import { resolvePluginCandidateInstallOwner } from "./candidate-install-owner.js"; import type { PluginCandidate } from "./discovery.js"; -import { createManifestPluginRecord, validatePluginConfig } from "./loader-shared.js"; +import { + createManifestPluginRecord, + createPluginCandidatesFromManifestRegistry, + validatePluginConfig, +} from "./loader-shared.js"; +import { recordPluginManifestInstallOwner } from "./manifest-install-owner.js"; import type { PluginManifestRecord } from "./manifest-registry.js"; const emptyObjectSchema = { @@ -57,6 +63,25 @@ describe("createManifestPluginRecord", () => { }); }); +describe("createPluginCandidatesFromManifestRegistry", () => { + it("preserves runtime child identity and package ownership", () => { + const childRecord = recordPluginManifestInstallOwner( + { ...manifestRecord, id: "example/child" }, + "example", + ); + + const candidate = createPluginCandidatesFromManifestRegistry({ + plugins: [childRecord], + diagnostics: [], + })[0]; + expect(candidate).toMatchObject({ + idHint: "example/child", + effectivePluginId: "example/child", + }); + expect(resolvePluginCandidateInstallOwner(candidate!)).toBe("example"); + }); +}); + describe("validatePluginConfig empty schema classification", () => { it("validates pattern properties instead of requiring empty config", () => { const schema = { diff --git a/src/plugins/loader-shared.ts b/src/plugins/loader-shared.ts index 2ce142e21aac..c8a9a716c470 100644 --- a/src/plugins/loader-shared.ts +++ b/src/plugins/loader-shared.ts @@ -12,6 +12,7 @@ import { resolveMemoryDreamingConfig, resolveMemoryDreamingPluginConfig, } from "../memory-host-sdk/dreaming.js"; +import { recordPluginCandidateInstallOwner } from "./candidate-install-owner.js"; import { resolveEffectiveEnableState, type NormalizedPluginsConfig, @@ -28,6 +29,10 @@ import { import { collectPluginManifestCompatCodes } from "./installed-plugin-index-record-builder.js"; import { createPluginRecord } from "./loader-records.js"; import type { PluginLoadOptions, PluginRuntimeSubagentMode } from "./loader-types.js"; +import { + isPluginManifestInstallOwnerAmbiguous, + resolvePluginManifestInstallOwner, +} from "./manifest-install-owner.js"; import type { PluginManifestRecord, PluginManifestRegistry } from "./manifest-registry.js"; import type { PluginDiagnostic } from "./manifest-types.js"; import type { PluginRecord, PluginRegistry } from "./registry.js"; @@ -154,17 +159,27 @@ export function matchesScopedPluginOrDreamingSidecar(params: { export function createPluginCandidatesFromManifestRegistry( manifestRegistry: PluginManifestRegistry, ): PluginCandidate[] { - return manifestRegistry.plugins.map((record) => ({ - idHint: record.id, - rootDir: record.rootDir, - source: record.source, - ...(record.setupSource !== undefined ? { setupSource: record.setupSource } : {}), - origin: record.origin, - ...(record.workspaceDir !== undefined ? { workspaceDir: record.workspaceDir } : {}), - ...(record.format !== undefined ? { format: record.format } : {}), - ...(record.bundleFormat !== undefined ? { bundleFormat: record.bundleFormat } : {}), - ...(record.packageManifest !== undefined ? { packageManifest: record.packageManifest } : {}), - })); + return manifestRegistry.plugins.map((record) => { + const installOwner = resolvePluginManifestInstallOwner(record); + return recordPluginCandidateInstallOwner( + { + idHint: record.id, + effectivePluginId: record.id, + rootDir: record.rootDir, + source: record.source, + ...(record.setupSource !== undefined ? { setupSource: record.setupSource } : {}), + origin: record.origin, + ...(record.workspaceDir !== undefined ? { workspaceDir: record.workspaceDir } : {}), + ...(record.format !== undefined ? { format: record.format } : {}), + ...(record.bundleFormat !== undefined ? { bundleFormat: record.bundleFormat } : {}), + ...(record.packageManifest !== undefined + ? { packageManifest: record.packageManifest } + : {}), + }, + installOwner, + isPluginManifestInstallOwnerAmbiguous(record), + ); + }); } class PluginLoadFailureError extends Error { diff --git a/src/plugins/management-service.test.ts b/src/plugins/management-service.test.ts index 884233f6b399..71ea0917fc94 100644 --- a/src/plugins/management-service.test.ts +++ b/src/plugins/management-service.test.ts @@ -133,6 +133,10 @@ function metadataSnapshot(params: { icon?: string; }) { const id = params.id ?? "workboard"; + const origin = params.origin ?? "bundled"; + const installRecord = + params.installRecord ?? + (origin === "global" ? { source: "path", installPath: `/tmp/${id}` } : undefined); const manifest = { id, name: params.name ?? "Workboard", @@ -144,7 +148,7 @@ function metadataSnapshot(params: { cliBackends: [], skills: [], hooks: [], - origin: params.origin ?? "bundled", + origin, rootDir: `/tmp/${id}`, source: `/tmp/${id}/index.ts`, manifestPath: `/tmp/${id}/openclaw.plugin.json`, @@ -154,12 +158,14 @@ function metadataSnapshot(params: { plugins: [ { pluginId: id, + ...(origin === "global" ? { installOwner: id } : {}), packageName: `@openclaw/${id}`, - origin: params.origin ?? "bundled", + origin, enabled: params.enabled, + rootDir: `/tmp/${id}`, }, ], - installRecords: params.installRecord ? { [id]: params.installRecord } : {}, + installRecords: installRecord ? { [id]: installRecord } : {}, }, byPluginId: new Map([[id, manifest]]), plugins: [manifest], @@ -213,8 +219,7 @@ const hostedDiffsEntry = { }, }; -// Mirrors the current default ClawHub feed shape: package identity lives in a -// source candidate while runtime/editorial metadata remains local. +// Mirrors the ClawHub feed: package identity is remote, while runtime metadata stays local. const hostedFeedDiffsEntry = { id: "@openclaw/diffs", title: "Diffs", @@ -818,8 +823,7 @@ describe("plugin management service", () => { env, }), ).rejects.toBe(conflict); - expect(mocks.installRecords).toHaveBeenCalledWith({ env }); - expect(mocks.planUninstall).toHaveBeenCalledWith({ + expect(mocks.planUninstall.mock.calls[0]?.[0]).toMatchObject({ config: { plugins: { installs: { @@ -833,7 +837,6 @@ describe("plugin management service", () => { }, pluginId: "demo", deleteFiles: true, - extensionsDir: expect.any(String), }); expect(mocks.applyUninstall).toHaveBeenCalledWith({ target: targetDir }); }); @@ -913,6 +916,7 @@ describe("plugin management service", () => { mocks.replaceConfig.mockResolvedValue({}); mocks.refreshRegistry.mockResolvedValue(undefined); mocks.metadata + .mockReturnValueOnce(metadataSnapshot({ enabled: true, id: "demo", origin: "global" })) .mockReturnValueOnce(metadataSnapshot({ enabled: true, id: "demo", origin: "global" })) .mockReturnValueOnce(metadataSnapshot({ enabled: false })) .mockReturnValueOnce(metadataSnapshot({ enabled: true })); @@ -1050,7 +1054,6 @@ describe("plugin management service", () => { writeOptions: prepared.writeOptions, }), ); - // Transient install records never persist into the written config document. expect( expectDefined( mocks.commitRecords.mock.calls[0], diff --git a/src/plugins/management-service.ts b/src/plugins/management-service.ts index 50f0e47b2772..4a36c6030622 100644 --- a/src/plugins/management-service.ts +++ b/src/plugins/management-service.ts @@ -51,6 +51,7 @@ import { withPluginInstallRecords, withoutPluginInstallRecords, } from "./installed-plugin-index-records.js"; +import { resolveInstalledPluginPackageOwnership } from "./installed-plugin-package-ownership.js"; import type { PluginManifestRecord } from "./manifest-registry.js"; import type { PluginDiagnostic } from "./manifest-types.js"; import { @@ -81,12 +82,15 @@ import { refreshPluginRegistryAfterConfigMutation } from "./registry-refresh.js" import { applySlotSelectionForPlugin } from "./slot-selection.js"; import { setPluginEnabledInConfig } from "./toggle-config.js"; import { collectClawPluginUninstallWarnings } from "./uninstall-claw-references.js"; +import { + prepareConfigForPendingPluginDirectoryRemovalSet, + recordPluginPackageUninstallPlan, +} from "./uninstall-package-plan.js"; import { applyPluginUninstallDirectoryRemoval, formatUninstallActionLabels, planPluginUninstall, pluginUninstallTargetExists, - prepareConfigForPendingPluginDirectoryRemoval, } from "./uninstall.js"; type ManagedPluginCatalogEntry = { @@ -536,6 +540,7 @@ type PluginIndexRecord = PluginMetadataSnapshot["index"]["plugins"][number]; function resolveInstalledHostedOfficialEntry(params: { record: PluginIndexRecord; + installOwner?: string; installRecord?: PluginInstallRecord; officialEntries: readonly OfficialExternalPluginCatalogEntry[]; bundledOfficialEntries: readonly OfficialExternalPluginCatalogEntry[]; @@ -543,15 +548,16 @@ function resolveInstalledHostedOfficialEntry(params: { entry?: OfficialExternalPluginCatalogEntry; hasPublishedIdentity: boolean; } { + const identityPluginId = params.installOwner ?? params.record.pluginId; const trustedOfficialClawHubSpec = params.installRecord ? resolveTrustedSourceLinkedOfficialClawHubSpec({ - pluginId: params.record.pluginId, + pluginId: identityPluginId, record: params.installRecord, }) : undefined; const trustedOfficialNpmSpec = params.installRecord ? resolveTrustedSourceLinkedOfficialNpmSpec({ - pluginId: params.record.pluginId, + pluginId: identityPluginId, record: params.installRecord, }) : undefined; @@ -630,9 +636,12 @@ function resolvePluginIconUrlFromCatalogFacts(params: { if (!record) { return resolveOfficialCatalogIconUrl(params.officialEntries, normalizedPluginId); } + const ownership = resolveInstalledPluginPackageOwnership(params.metadata.index, record.pluginId); + const installOwner = ownership.ok ? ownership.value.installOwner : undefined; const { entry: officialEntry } = resolveInstalledHostedOfficialEntry({ record, - installRecord: params.metadata.index.installRecords[record.pluginId], + ...(installOwner ? { installOwner } : {}), + installRecord: installOwner ? params.metadata.index.installRecords[installOwner] : undefined, officialEntries: params.officialEntries, bundledOfficialEntries: params.bundledOfficialEntries ?? listOfficialExternalPluginCatalogEntries(), @@ -723,9 +732,12 @@ export async function listManagedPlugins(params: { const plugins = metadata.index.plugins.map((record): ManagedPluginCatalogEntry => { const manifest = metadata.byPluginId.get(record.pluginId); const localCatalog = normalizeCatalogMetadata(manifest?.catalog); - const installRecord = metadata.index.installRecords[record.pluginId]; + const ownership = resolveInstalledPluginPackageOwnership(metadata.index, record.pluginId); + const installOwner = ownership.ok ? ownership.value.installOwner : undefined; + const installRecord = installOwner ? metadata.index.installRecords[installOwner] : undefined; const { entry: officialEntry, hasPublishedIdentity } = resolveInstalledHostedOfficialEntry({ record, + ...(installOwner ? { installOwner } : {}), installRecord, officialEntries: officialCatalog.entries, bundledOfficialEntries, @@ -750,8 +762,7 @@ export async function listManagedPlugins(params: { const kind = normalizeKinds(manifest?.kind); const category = derivePluginCategory(manifest); // Only externally installed plugins (tracked install record, non-bundled) can be removed. - const removable = - record.origin !== "bundled" && Boolean(metadata.index.installRecords[record.pluginId]); + const removable = record.origin !== "bundled" && Boolean(installOwner); // Prefer human labels over package specifiers: the registry backfills a // missing manifest name with the npm package name, which is an install // spec rather than a display name. @@ -1017,14 +1028,19 @@ async function cleanupFailedManagedPluginInstall(params: { ]; } - const plan = planPluginUninstall({ - config: { - plugins: { installs: { [params.pluginId]: params.install } }, - }, - pluginId: params.pluginId, - deleteFiles: true, - extensionsDir: params.extensionsDir, - }); + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: { + plugins: { installs: { [params.pluginId]: params.install } }, + }, + pluginId: params.pluginId, + deleteFiles: true, + extensionsDir: params.extensionsDir, + }, + { runtimePluginIds: [] }, + ), + ); if (!plan.ok) { return [`Could not plan cleanup for failed plugin install: ${plan.error}`]; } @@ -1436,7 +1452,20 @@ export async function installManagedPlugin(params: { env, officialCatalog, }); - const plugin = catalog.plugins.find((entry) => entry.id === installed.pluginId); + const installedMetadata = resolvePluginMetadataSnapshot( + resolveManagedPluginMetadataParams(installed.config, env), + ); + const installedOwnership = resolveInstalledPluginPackageOwnership( + installedMetadata.index, + installed.pluginId, + env, + ); + if (!installedOwnership.ok) { + throw new ManagedPluginLifecycleError(installedOwnership.error); + } + const installedPluginIds = installedOwnership.value.pluginIds; + const representativePluginId = installedPluginIds[0]!; + const plugin = catalog.plugins.find((entry) => entry.id === representativePluginId); if (!plugin) { throw new ManagedPluginLifecycleError( `installed plugin missing from refreshed registry: ${installed.pluginId}`, @@ -1444,7 +1473,18 @@ export async function installManagedPlugin(params: { } return { plugin, - ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {}), + ...(installedPluginIds.length > 1 || warnings.length > 0 + ? { + warnings: [ + ...(installedPluginIds.length > 1 + ? [ + `Installed package "${installed.pluginId}" with plugin entries: ${installedPluginIds.join(", ")}.`, + ] + : []), + ...new Set(warnings), + ], + } + : {}), }; }); } @@ -1546,16 +1586,40 @@ export async function uninstallManagedPlugin(params: { `bundled plugin cannot be uninstalled: ${pluginId}; disable it instead`, ); } - // Preserve manifest ownership exactly; only missing metadata uses the plugin-id fallback. - const channelIds = metadata.byPluginId.get(pluginId)?.channels; - const extensionsDir = resolveDefaultPluginExtensionsDir(env); - const initialPlan = planPluginUninstall({ - config: configWithRecords, - pluginId, - ...(channelIds ? { channelIds } : {}), - deleteFiles: true, - extensionsDir, + if (!record && !Object.hasOwn(installRecords, pluginId)) { + throw new ManagedPluginLifecycleError(`Plugin not found: ${pluginId}`); + } + const ownership = resolveInstalledPluginPackageOwnership(metadata.index, pluginId, env); + if (!ownership.ok) { + throw new ManagedPluginLifecycleError(ownership.error); + } + const { installOwner, pluginIds: ownedPluginIds } = ownership.value; + const ownedManifests = ownedPluginIds.flatMap((entryId) => { + const manifest = metadata.byPluginId.get(entryId); + return manifest ? [manifest] : []; }); + const channelIds = + ownedManifests.length > 0 + ? uniqueStrings(ownedManifests.flatMap((manifest) => manifest.channels)) + : undefined; + const extensionsDir = resolveDefaultPluginExtensionsDir(env); + const initialPlan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: configWithRecords, + pluginId: installOwner, + ...(channelIds !== undefined ? { channelIds } : {}), + deleteFiles: true, + extensionsDir, + }, + { + runtimePluginIds: ownedPluginIds, + runtimeLoadPaths: ownedPluginIds.flatMap( + (entryId) => metadata.byPluginId.get(entryId)?.source ?? [], + ), + }, + ), + ); if (!initialPlan.ok) { throw new ManagedPluginLifecycleError(initialPlan.error); } @@ -1563,9 +1627,9 @@ export async function uninstallManagedPlugin(params: { let finalSnapshot = snapshot; let directoryResult = { directoryRemoved: false, warnings: [] as string[] }; if (plan.directoryRemoval) { - const disabledConfig = prepareConfigForPendingPluginDirectoryRemoval( + const disabledConfig = prepareConfigForPendingPluginDirectoryRemovalSet( snapshot.config, - pluginId, + ownedPluginIds, ); await replaceConfigFile({ nextConfig: disabledConfig, @@ -1587,20 +1651,30 @@ export async function uninstallManagedPlugin(params: { finalSnapshot.config, installRecords, ); - const refreshedPlan = planPluginUninstall({ - config: refreshedConfigWithRecords, - pluginId, - ...(channelIds ? { channelIds } : {}), - deleteFiles: true, - extensionsDir, - }); + const refreshedPlan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: refreshedConfigWithRecords, + pluginId: installOwner, + ...(channelIds !== undefined ? { channelIds } : {}), + deleteFiles: true, + extensionsDir, + }, + { + runtimePluginIds: ownedPluginIds, + runtimeLoadPaths: ownedPluginIds.flatMap( + (entryId) => metadata.byPluginId.get(entryId)?.source ?? [], + ), + }, + ), + ); if (!refreshedPlan.ok) { throw new ManagedPluginLifecycleError(refreshedPlan.error); } plan = refreshedPlan; } const nextConfig = withoutPluginInstallRecords(plan.config); - const nextInstallRecords = removePluginInstallRecordFromRecords(installRecords, pluginId); + const nextInstallRecords = removePluginInstallRecordFromRecords(installRecords, installOwner); await commitPluginInstallRecordsWithConfig({ previousInstallRecords: installRecords, nextInstallRecords, @@ -1610,10 +1684,15 @@ export async function uninstallManagedPlugin(params: { }); const warnings = [ ...collectClawPluginUninstallWarnings({ - pluginId, - installRecord: installRecords[pluginId], + pluginId: installOwner, + installRecord: installRecords[installOwner], env, }), + ...(pluginId !== installOwner || ownedPluginIds.length > 1 + ? [ + `Uninstalled package "${installOwner}" and all owned plugin entries: ${ownedPluginIds.join(", ")}.`, + ] + : []), ...directoryResult.warnings, ]; await refreshPluginRegistryAfterConfigMutation({ @@ -1629,7 +1708,7 @@ export async function uninstallManagedPlugin(params: { directory: directoryResult.directoryRemoved, }); return { - pluginId, + pluginId: installOwner, removed, ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {}), }; diff --git a/src/plugins/management-service.uninstall-ownership.test.ts b/src/plugins/management-service.uninstall-ownership.test.ts index 990ebed98c71..ef74d7088ad4 100644 --- a/src/plugins/management-service.uninstall-ownership.test.ts +++ b/src/plugins/management-service.uninstall-ownership.test.ts @@ -1,4 +1,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; +import { recordInstalledPluginIndexInstallOwner } from "./installed-plugin-index-install-owner.js"; +import { recordPluginManifestInstallOwner } from "./manifest-install-owner.js"; +import { resolvePluginPackageUninstallPlan } from "./uninstall-package-plan.js"; const mocks = vi.hoisted(() => ({ commitRecords: vi.fn(), @@ -46,7 +49,7 @@ vi.mock("./uninstall.js", async (importOriginal) => { return { ...original, planPluginUninstall: vi.fn(original.planPluginUninstall) }; }); -const { uninstallManagedPlugin } = await import("./management-service.js"); +const { listManagedPlugins, uninstallManagedPlugin } = await import("./management-service.js"); const { planPluginUninstall } = await import("./uninstall.js"); describe("plugin management uninstall channel ownership", () => { @@ -63,7 +66,6 @@ describe("plugin management uninstall channel ownership", () => { channelIds: ["owned-channel", "owned-channel-backup"], }, { label: "an enabled channel plugin", enabled: true, channelIds: ["owned-channel"] }, - { label: "a plugin with unavailable manifest metadata", enabled: false, channelIds: undefined }, ])( "preserves manifest channel ownership when uninstalling $label", async ({ enabled, channelIds }) => { @@ -87,29 +89,33 @@ describe("plugin management uninstall channel ownership", () => { writeOptions: { expectedConfigPath: "/tmp/openclaw.json" }, }); mocks.installRecords.mockResolvedValue({ [pluginId]: installRecord }); - const manifest = - channelIds === undefined ? undefined : { id: pluginId, channels: channelIds }; + const manifest = recordPluginManifestInstallOwner( + { id: pluginId, channels: channelIds }, + pluginId, + ); mocks.metadata.mockReturnValue({ index: { - plugins: manifest ? [{ pluginId, origin: "global", enabled }] : [], + plugins: [ + recordInstalledPluginIndexInstallOwner( + { pluginId, origin: "global", enabled, rootDir: installPath }, + pluginId, + ), + ], installRecords: { [pluginId]: installRecord }, }, - byPluginId: new Map(manifest ? [[pluginId, manifest]] : []), + byPluginId: new Map([[pluginId, manifest]]), normalizePluginId: (rawPluginId: string) => rawPluginId, }); const result = await uninstallManagedPlugin({ pluginId, env: {} }); - const ownedChannelIds = channelIds ?? [pluginId]; + const ownedChannelIds = channelIds; expect(planPluginUninstall).toHaveBeenCalledWith( expect.objectContaining({ pluginId, - ...(channelIds === undefined ? {} : { channelIds }), + channelIds, }), ); - if (channelIds === undefined) { - expect(vi.mocked(planPluginUninstall).mock.calls[0]?.[0]).not.toHaveProperty("channelIds"); - } expect(mocks.commitRecords).toHaveBeenCalledWith( expect.objectContaining({ nextConfig: expect.objectContaining({ @@ -129,4 +135,170 @@ describe("plugin management uninstall channel ownership", () => { ]); }, ); + + it("fails closed when an owner record has no authoritative child metadata", async () => { + const pluginId = "custom-plugin"; + const installPath = "/tmp/openclaw-managed-missing-children"; + const installRecord = { source: "path", sourcePath: installPath, installPath } as const; + mocks.readConfig.mockResolvedValue({ + snapshot: { + valid: true, + parsed: {}, + path: "/tmp/openclaw.json", + sourceConfig: { plugins: { entries: { [pluginId]: { enabled: true } } } }, + hash: "base-hash", + }, + writeOptions: { expectedConfigPath: "/tmp/openclaw.json" }, + }); + mocks.installRecords.mockResolvedValue({ [pluginId]: installRecord }); + mocks.metadata.mockReturnValue({ + index: { + plugins: [{ pluginId, origin: "global", enabled: true, rootDir: installPath }], + installRecords: { [pluginId]: installRecord }, + }, + byPluginId: new Map(), + normalizePluginId: (rawPluginId: string) => rawPluginId, + }); + + await expect(uninstallManagedPlugin({ pluginId, env: {} })).rejects.toThrow( + "no authoritative package-owner metadata", + ); + expect(mocks.commitRecords).not.toHaveBeenCalled(); + }); + + it("resolves a child request to one package owner and removes every sibling policy", async () => { + const installPath = "/tmp/openclaw-managed-linked-pack"; + const installRecord = { source: "path", sourcePath: installPath, installPath } as const; + mocks.readConfig.mockResolvedValue({ + snapshot: { + valid: true, + parsed: {}, + path: "/tmp/openclaw.json", + sourceConfig: { + plugins: { + allow: ["pack/one", "pack/two", "other"], + entries: { + "pack/one": { enabled: true }, + "pack/two": { enabled: false }, + other: { enabled: true }, + }, + }, + }, + hash: "pack-hash", + }, + writeOptions: { expectedConfigPath: "/tmp/openclaw.json" }, + }); + mocks.installRecords.mockResolvedValue({ pack: installRecord }); + const manifests: Array<[string, { id: string; channels: string[] }]> = [ + ["pack/one", recordPluginManifestInstallOwner({ id: "pack/one", channels: [] }, "pack")], + ["pack/two", recordPluginManifestInstallOwner({ id: "pack/two", channels: [] }, "pack")], + ]; + mocks.metadata.mockReturnValue({ + index: { + plugins: [ + recordInstalledPluginIndexInstallOwner( + { + pluginId: "pack/one", + origin: "global", + enabled: true, + rootDir: installPath, + }, + "pack", + ), + recordInstalledPluginIndexInstallOwner( + { + pluginId: "pack/two", + origin: "global", + enabled: false, + rootDir: installPath, + }, + "pack", + ), + ], + installRecords: { pack: installRecord }, + }, + byPluginId: new Map(manifests), + normalizePluginId: (pluginId: string) => pluginId, + }); + + const result = await uninstallManagedPlugin({ pluginId: "pack/two", env: {} }); + + expect(planPluginUninstall).toHaveBeenCalledWith( + expect.objectContaining({ + pluginId: "pack", + }), + ); + expect( + resolvePluginPackageUninstallPlan(vi.mocked(planPluginUninstall).mock.calls[0]![0]), + ).toEqual({ + runtimePluginIds: ["pack/one", "pack/two"], + runtimeLoadPaths: [], + }); + expect(mocks.commitRecords).toHaveBeenCalledWith( + expect.objectContaining({ + nextInstallRecords: {}, + nextConfig: { + plugins: { + allow: ["other"], + entries: { other: { enabled: true } }, + }, + }, + }), + ); + expect(result.pluginId).toBe("pack"); + expect(result.warnings).toContain( + 'Uninstalled package "pack" and all owned plugin entries: pack/one, pack/two.', + ); + }); + + it("marks every child removable through its package install owner", async () => { + const installRecord = { + source: "path", + sourcePath: "/tmp/pack", + installPath: "/tmp/pack", + }; + const manifests = ["pack/one", "pack/two"].map((id) => ({ + id, + channels: [], + providers: [], + cliBackends: [], + skills: [], + hooks: [], + origin: "global", + rootDir: "/tmp/pack", + source: `/tmp/pack/${id.endsWith("one") ? "one" : "two"}.js`, + manifestPath: "/tmp/pack/openclaw.plugin.json", + })); + mocks.metadata.mockReturnValue({ + index: { + plugins: manifests.map((manifest, index) => + recordInstalledPluginIndexInstallOwner( + { + pluginId: manifest.id, + packageName: "@acme/pack", + origin: "global", + enabled: index === 0, + rootDir: "/tmp/pack", + }, + "pack", + ), + ), + installRecords: { pack: installRecord }, + }, + byPluginId: new Map(manifests.map((manifest) => [manifest.id, manifest])), + diagnostics: [], + normalizePluginId: (pluginId: string) => pluginId, + }); + + const catalog = await listManagedPlugins({ + config: {}, + env: {}, + officialCatalog: { entries: [] }, + }); + + expect(catalog.plugins.map(({ id, removable }) => ({ id, removable }))).toEqual([ + { id: "pack/one", removable: true }, + { id: "pack/two", removable: true }, + ]); + }); }); diff --git a/src/plugins/manifest-install-owner.ts b/src/plugins/manifest-install-owner.ts new file mode 100644 index 000000000000..5dd32d04beef --- /dev/null +++ b/src/plugins/manifest-install-owner.ts @@ -0,0 +1,33 @@ +const PLUGIN_MANIFEST_INSTALL_OWNER = Symbol.for("openclaw.pluginManifestInstallOwner"); + +type PluginManifestInstallOwner = { installOwner?: string; ambiguous?: true }; + +export function recordPluginManifestInstallOwner( + record: T, + installOwner: string | undefined, + ambiguous = false, +): T { + if (!installOwner && !ambiguous) { + return record; + } + Object.defineProperty(record, PLUGIN_MANIFEST_INSTALL_OWNER, { + configurable: false, + enumerable: true, + value: ambiguous ? { ambiguous: true } : { installOwner }, + }); + return record; +} + +function readPluginManifestInstallOwner(record: object): PluginManifestInstallOwner | undefined { + return (record as { [PLUGIN_MANIFEST_INSTALL_OWNER]?: PluginManifestInstallOwner })[ + PLUGIN_MANIFEST_INSTALL_OWNER + ]; +} + +export function resolvePluginManifestInstallOwner(record: object): string | undefined { + return readPluginManifestInstallOwner(record)?.installOwner; +} + +export function isPluginManifestInstallOwnerAmbiguous(record: object): boolean { + return readPluginManifestInstallOwner(record)?.ambiguous === true; +} diff --git a/src/plugins/manifest-registry-installed.test.ts b/src/plugins/manifest-registry-installed.test.ts index 4dd9a009cf2f..4d63746f2595 100644 --- a/src/plugins/manifest-registry-installed.test.ts +++ b/src/plugins/manifest-registry-installed.test.ts @@ -3,11 +3,20 @@ import fs from "node:fs"; import path from "node:path"; import { expectDefined } from "@openclaw/normalization-core"; import { afterEach, describe, expect, it, vi } from "vitest"; +import { + recordInstalledPluginIndexInstallOwner, + resolveInstalledPluginIndexInstallOwner, +} from "./installed-plugin-index-install-owner.js"; import { readPersistedInstalledPluginIndex, writePersistedInstalledPluginIndex, } from "./installed-plugin-index-store.js"; -import type { InstalledPluginIndex } from "./installed-plugin-index.js"; +import { loadInstalledPluginIndex, type InstalledPluginIndex } from "./installed-plugin-index.js"; +import { + hasMissingInstalledPluginOwnerMetadata, + resolveInstalledPluginPackageOwnership, +} from "./installed-plugin-package-ownership.js"; +import { resolvePluginManifestInstallOwner } from "./manifest-install-owner.js"; import { loadPluginManifestRegistryForInstalledIndex, resolveInstalledManifestRegistryIndexFingerprint, @@ -375,6 +384,190 @@ describe("loadPluginManifestRegistryForInstalledIndex", () => { }); }); + it("preserves package entry identities through a persisted cold reload", async () => { + const stateDir = makeTempDir(); + const packageDir = path.join(stateDir, "extensions", "pack"); + fs.mkdirSync(packageDir, { recursive: true }); + fs.writeFileSync( + path.join(packageDir, "package.json"), + JSON.stringify({ + name: "pack", + version: "1.0.0", + openclaw: { extensions: ["./one.cjs", "./two.cjs"] }, + }), + "utf8", + ); + fs.writeFileSync( + path.join(packageDir, "openclaw.plugin.json"), + JSON.stringify({ id: "pack", configSchema: { type: "object" } }), + "utf8", + ); + for (const entry of ["one", "two"]) { + fs.writeFileSync( + path.join(packageDir, `${entry}.cjs`), + `module.exports = { id: "pack/${entry}", register() {} };\n`, + "utf8", + ); + } + const config = { + plugins: { + entries: { + "pack/one": { enabled: true }, + "pack/two": { enabled: false }, + }, + }, + }; + const env = { + OPENCLAW_DISABLE_BUNDLED_PLUGINS: "1", + OPENCLAW_STATE_DIR: stateDir, + OPENCLAW_VERSION: "2026.4.25", + VITEST: "true", + }; + const installRecords = { + pack: { + source: "path" as const, + sourcePath: packageDir, + installPath: packageDir, + }, + }; + const index = loadInstalledPluginIndex({ config, env, installRecords, stateDir }); + + expect( + index.plugins.map((plugin) => ({ + pluginId: plugin.pluginId, + installOwner: resolveInstalledPluginIndexInstallOwner(plugin), + enabled: plugin.enabled, + })), + ).toEqual([ + { pluginId: "pack/one", installOwner: "pack", enabled: true }, + { pluginId: "pack/two", installOwner: "pack", enabled: false }, + ]); + await writePersistedInstalledPluginIndex(index, { stateDir }); + clearPluginMetadataLifecycleCaches(); + const persisted = await readPersistedInstalledPluginIndex({ stateDir }); + if (!persisted) { + throw new Error("expected persisted package plugin index"); + } + expect(resolveInstalledPluginPackageOwnership(persisted, "pack/one")).toMatchObject({ + ok: true, + value: { installOwner: "pack", pluginIds: ["pack/one", "pack/two"] }, + }); + + const allEntries = loadPluginManifestRegistryForInstalledIndex({ + index: persisted, + config, + env, + includeDisabled: true, + }); + expect( + allEntries.plugins.map(({ id, source }) => ({ id, source: path.basename(source) })), + ).toEqual([ + { id: "pack/one", source: "one.cjs" }, + { id: "pack/two", source: "two.cjs" }, + ]); + expect(allEntries.plugins.map(resolvePluginManifestInstallOwner)).toEqual(["pack", "pack"]); + + const enabledEntries = loadPluginManifestRegistryForInstalledIndex({ + index: persisted, + config, + env, + }); + expect(enabledEntries.plugins.map(({ id }) => id)).toEqual(["pack/one"]); + + const ownerless = { + ...persisted, + plugins: persisted.plugins.map((plugin) => { + const { + installOwner: _installOwner, + installOwnerAmbiguous: _installOwnerAmbiguous, + ...ownerlessPlugin + } = plugin as typeof plugin & { + installOwner?: string; + installOwnerAmbiguous?: true; + }; + return ownerlessPlugin; + }), + }; + expect(resolveInstalledPluginPackageOwnership(ownerless, "pack/one").ok).toBe(false); + + const orphanedOwner = { + ...persisted, + installRecords: { + ...persisted.installRecords, + orphaned: { + source: "path" as const, + sourcePath: path.join(stateDir, "removed-orphan"), + installPath: path.join(stateDir, "removed-orphan"), + }, + }, + }; + expect(resolveInstalledPluginPackageOwnership(orphanedOwner, "orphaned").ok).toBe(false); + expect(hasMissingInstalledPluginOwnerMetadata(orphanedOwner, env)).toBe(false); + + const legacyAmbiguous = { + ...ownerless, + installRecords: { + "pack/one": installRecords.pack, + "pack/two": installRecords.pack, + }, + }; + expect(resolveInstalledPluginPackageOwnership(legacyAmbiguous, "pack/one").ok).toBe(false); + expect(hasMissingInstalledPluginOwnerMetadata(legacyAmbiguous, env)).toBe(true); + + const packageAlias = path.join(stateDir, "pack-alias"); + fs.symlinkSync(packageDir, packageAlias, process.platform === "win32" ? "junction" : "dir"); + const aliasedAmbiguous = { + ...ownerless, + installRecords: { + "pack/one": installRecords.pack, + "pack/two": { + ...installRecords.pack, + sourcePath: packageAlias, + installPath: packageAlias, + }, + }, + }; + expect(resolveInstalledPluginPackageOwnership(aliasedAmbiguous, "pack/one").ok).toBe(false); + expect(hasMissingInstalledPluginOwnerMetadata(aliasedAmbiguous, env)).toBe(true); + + const unrelatedOwner = "unrelated"; + const relationScoped = { + ...aliasedAmbiguous, + plugins: [ + ...aliasedAmbiguous.plugins, + recordInstalledPluginIndexInstallOwner( + { + ...aliasedAmbiguous.plugins[0]!, + pluginId: unrelatedOwner, + rootDir: path.join(stateDir, unrelatedOwner), + }, + unrelatedOwner, + ), + ], + installRecords: { + ...aliasedAmbiguous.installRecords, + [unrelatedOwner]: { + source: "path" as const, + sourcePath: path.join(stateDir, unrelatedOwner), + installPath: path.join(stateDir, unrelatedOwner), + }, + }, + }; + expect(resolveInstalledPluginPackageOwnership(relationScoped, unrelatedOwner)).toMatchObject({ + ok: true, + value: { installOwner: unrelatedOwner, pluginIds: [unrelatedOwner] }, + }); + + const ambiguous = { + ...legacyAmbiguous, + plugins: ownerless.plugins.map((plugin) => + recordInstalledPluginIndexInstallOwner(plugin, undefined, true), + ), + }; + expect(resolveInstalledPluginPackageOwnership(ambiguous, "pack/one").ok).toBe(false); + expect(hasMissingInstalledPluginOwnerMetadata(ambiguous, env)).toBe(true); + }); + it("reuses a prepared manifest graph without reopening plugin manifests", () => { const rootDir = makeTempDir(); writePlugin(rootDir, "installed", "installed-"); diff --git a/src/plugins/manifest-registry-installed.ts b/src/plugins/manifest-registry-installed.ts index b207a73700b6..bdad5cd8d8f5 100644 --- a/src/plugins/manifest-registry-installed.ts +++ b/src/plugins/manifest-registry-installed.ts @@ -11,8 +11,13 @@ import { import type { OpenClawConfig } from "../config/types.openclaw.js"; import { tryReadJsonSync } from "../infra/json-files.js"; import { pruneMapToMaxSize } from "../infra/map-size.js"; +import { recordPluginCandidateInstallOwner } from "./candidate-install-owner.js"; import type { PluginCandidate } from "./discovery.js"; import { hashJson } from "./installed-plugin-index-hash.js"; +import { + isInstalledPluginIndexInstallOwnerAmbiguous, + resolveInstalledPluginIndexInstallOwner, +} from "./installed-plugin-index-install-owner.js"; import type { InstalledPluginIndex, InstalledPluginIndexRecord } from "./installed-plugin-index.js"; import { extractPluginInstallRecordsFromInstalledPluginIndex } from "./installed-plugin-index.js"; import { @@ -508,27 +513,32 @@ function toPluginCandidate( ): PluginCandidate { const rootDir = resolveInstalledPluginRootDir(record); const packageMetadata = resolveInstalledPackageMetadata(record, realpathCache); - return { - idHint: record.pluginId, - source: record.source ?? resolveFallbackPluginSource(record), - ...(record.setupSource ? { setupSource: record.setupSource } : {}), - rootDir, - origin: record.origin, - ...(record.format ? { format: record.format } : {}), - ...(record.bundleFormat ? { bundleFormat: record.bundleFormat } : {}), - ...(record.packageName ? { packageName: record.packageName } : {}), - ...(record.packageVersion ? { packageVersion: record.packageVersion } : {}), - ...(packageMetadata.packageManifest - ? { packageManifest: packageMetadata.packageManifest } - : {}), - ...(packageMetadata.packageDependencies - ? { packageDependencies: packageMetadata.packageDependencies } - : {}), - ...(packageMetadata.packageOptionalDependencies - ? { packageOptionalDependencies: packageMetadata.packageOptionalDependencies } - : {}), - packageDir: rootDir, - }; + return recordPluginCandidateInstallOwner( + { + idHint: record.pluginId, + effectivePluginId: record.pluginId, + source: record.source ?? resolveFallbackPluginSource(record), + ...(record.setupSource ? { setupSource: record.setupSource } : {}), + rootDir, + origin: record.origin, + ...(record.format ? { format: record.format } : {}), + ...(record.bundleFormat ? { bundleFormat: record.bundleFormat } : {}), + ...(record.packageName ? { packageName: record.packageName } : {}), + ...(record.packageVersion ? { packageVersion: record.packageVersion } : {}), + ...(packageMetadata.packageManifest + ? { packageManifest: packageMetadata.packageManifest } + : {}), + ...(packageMetadata.packageDependencies + ? { packageDependencies: packageMetadata.packageDependencies } + : {}), + ...(packageMetadata.packageOptionalDependencies + ? { packageOptionalDependencies: packageMetadata.packageOptionalDependencies } + : {}), + packageDir: rootDir, + }, + resolveInstalledPluginIndexInstallOwner(record), + isInstalledPluginIndexInstallOwnerAmbiguous(record), + ); } export function loadPluginManifestRegistryForInstalledIndex(params: { diff --git a/src/plugins/manifest-registry.test.ts b/src/plugins/manifest-registry.test.ts index b8bd630437de..1ab61fb5e03f 100644 --- a/src/plugins/manifest-registry.test.ts +++ b/src/plugins/manifest-registry.test.ts @@ -5,7 +5,9 @@ import { afterEach, beforeAll, describe, expect, it, vi } from "vitest"; import { collectChannelSchemaMetadataCore } from "../config/channel-config-metadata.js"; import type { PluginInstallRecord } from "../config/types.plugins.js"; import { collectBundledChannelConfigsCore } from "./bundled-channel-config-metadata.js"; +import { recordPluginCandidateInstallOwner } from "./candidate-install-owner.js"; import type { PluginCandidate } from "./discovery.js"; +import { resolvePluginManifestInstallOwner } from "./manifest-install-owner.js"; import { loadPluginManifestRegistryCore } from "./manifest-registry.js"; import type { OpenClawPackageManifest } from "./manifest.js"; import { cleanupTrackedTempDirs, makeTrackedTempDir } from "./test-helpers/fs-fixtures.js"; @@ -82,21 +84,25 @@ function createPluginCandidate(params: { packageDir?: string; bundledManifest?: PluginCandidate["bundledManifest"]; bundledManifestPath?: string; + installOwner?: string; }): PluginCandidate { - return { - idHint: params.idHint, - source: path.join(params.rootDir, params.sourceName ?? "index.ts"), - rootDir: params.rootDir, - origin: params.origin, - format: params.format, - bundleFormat: params.bundleFormat, - packageName: params.packageName, - packageVersion: params.packageVersion, - packageManifest: params.packageManifest, - packageDir: params.packageDir, - bundledManifest: params.bundledManifest, - bundledManifestPath: params.bundledManifestPath, - }; + return recordPluginCandidateInstallOwner( + { + idHint: params.idHint, + source: path.join(params.rootDir, params.sourceName ?? "index.ts"), + rootDir: params.rootDir, + origin: params.origin, + format: params.format, + bundleFormat: params.bundleFormat, + packageName: params.packageName, + packageVersion: params.packageVersion, + packageManifest: params.packageManifest, + packageDir: params.packageDir, + bundledManifest: params.bundledManifest, + bundledManifestPath: params.bundledManifestPath, + }, + params.installOwner, + ); } function createMsteamsClawHubInstallRecord( @@ -127,6 +133,7 @@ function resolveMsteamsClawHubTrust(overrides: Partial = {} rootDir: dir, packageName: "@openclaw/msteams", origin: "global", + installOwner: "msteams", }), ], }); @@ -154,6 +161,7 @@ function resolveDiffsNpmTrust(overrides: Partial = {}) { rootDir: dir, packageName: "@openclaw/diffs", origin: "global", + installOwner: "diffs", }), ], }); @@ -828,6 +836,7 @@ describe("loadPluginManifestRegistry", () => { idHint: "zalouser", rootDir: globalDir, origin: "global", + installOwner: "zalouser", }), ], }); @@ -891,6 +900,7 @@ describe("loadPluginManifestRegistry", () => { idHint: "zalouser", rootDir: globalDir, origin: "global", + installOwner: "zalouser", }), createPluginCandidate({ idHint: "zalouser", @@ -909,6 +919,55 @@ describe("loadPluginManifestRegistry", () => { expect(resolveDiffsNpmTrust()).toBe(true); }); + it("associates official trust with every child owned by the installed package", () => { + const dir = makeTempDir(); + writeManifest(dir, { id: "diffs", configSchema: { type: "object" } }); + const registry = loadPluginManifestRegistryCore({ + installRecords: { + diffs: { + source: "npm", + spec: "@openclaw/diffs", + installPath: dir, + resolvedName: "@openclaw/diffs", + resolvedSpec: "@openclaw/diffs@2026.7.16", + }, + }, + candidates: [ + { + ...createPluginCandidate({ + idHint: "diffs/two", + rootDir: dir, + packageName: "@openclaw/diffs", + origin: "global", + installOwner: "diffs", + }), + effectivePluginId: "diffs/two", + }, + { + ...createPluginCandidate({ + idHint: "diffs/one", + rootDir: dir, + packageName: "@openclaw/diffs", + origin: "global", + installOwner: "diffs", + }), + effectivePluginId: "diffs/one", + }, + ], + }); + + expect( + registry.plugins.map((plugin) => ({ + id: plugin.id, + trustedOfficialInstall: plugin.trustedOfficialInstall, + installOwner: resolvePluginManifestInstallOwner(plugin), + })), + ).toEqual([ + { id: "diffs/two", trustedOfficialInstall: true, installOwner: "diffs" }, + { id: "diffs/one", trustedOfficialInstall: true, installOwner: "diffs" }, + ]); + }); + it.each([ { name: "npm-pack archive metadata", @@ -1091,6 +1150,7 @@ describe("loadPluginManifestRegistry", () => { rootDir: dir, packageName: "@openclaw/diagnostics-otel", origin: "global", + installOwner: "diagnostics-otel", }), ], }); @@ -1116,6 +1176,7 @@ describe("loadPluginManifestRegistry", () => { rootDir: dir, packageName: "@openclaw/diagnostics-otel", origin: "global", + installOwner: "diagnostics-otel", }), ], }); @@ -1144,6 +1205,7 @@ describe("loadPluginManifestRegistry", () => { rootDir: dir, packageName: "@openclaw/diagnostics-otel", origin: "config", + installOwner: "diagnostics-otel", }), ], }); @@ -1174,12 +1236,14 @@ describe("loadPluginManifestRegistry", () => { rootDir: dir, packageName: "@openclaw/diagnostics-prometheus", origin: "global", + installOwner: "diagnostics-prometheus", }), createPluginCandidate({ idHint: "diagnostics-prometheus", rootDir: dir, packageName: "@openclaw/diagnostics-prometheus", origin: "config", + installOwner: "diagnostics-prometheus", }), ], }); @@ -2844,18 +2908,21 @@ describe("loadPluginManifestRegistry", () => { }, }, candidates: [ - createPluginCandidate({ - idHint: "codex", - rootDir: dir, - packageDir: dir, - origin: "global", - packageManifest: { - install: { - npmSpec: "@openclaw/codex", - minHostVersion: "2026.3.22", + { + ...createPluginCandidate({ + idHint: "codex", + rootDir: dir, + packageDir: dir, + origin: "global", + packageManifest: { + install: { + npmSpec: "@openclaw/codex", + minHostVersion: "2026.3.22", + }, }, - }, - }), + installOwner: "codex", + }), + }, ], }); diff --git a/src/plugins/manifest-registry.ts b/src/plugins/manifest-registry.ts index 8b205b2448a3..078d2f714b73 100644 --- a/src/plugins/manifest-registry.ts +++ b/src/plugins/manifest-registry.ts @@ -13,6 +13,10 @@ import { isBlockedObjectKey } from "../infra/prototype-keys.js"; import { resolveUserPath } from "../utils.js"; import { resolveCompatibilityHostVersion } from "../version.js"; import { loadBundleManifest } from "./bundle-manifest.js"; +import { + isPluginCandidateInstallOwnerAmbiguous, + resolvePluginCandidateInstallOwner, +} from "./candidate-install-owner.js"; import { normalizePluginsConfigWithResolver } from "./config-policy.js"; import { isBundledPluginInsideDevSourceRoot } from "./dev-source-root.js"; import { @@ -24,6 +28,7 @@ import type { DoctorSessionRouteStateOwner } from "./doctor-session-route-state- import { shouldRejectHardlinkedPluginFiles } from "./hardlink-policy.js"; import { loadInstalledPluginIndexInstallRecordsSync } from "./installed-plugin-index-record-reader.js"; import type { PluginManifestCommandAlias } from "./manifest-command-aliases.js"; +import { recordPluginManifestInstallOwner } from "./manifest-install-owner.js"; import type { PluginBundleFormat, PluginConfigUiHint, @@ -779,6 +784,21 @@ function dedupePluginDiagnostics(diagnostics: PluginDiagnostic[]): PluginDiagnos return deduped; } +function resolveCandidateInstallOwner(params: { + pluginId: string; + candidate: PluginCandidate; + installRecords: Record; +}): string | undefined { + if (isPluginCandidateInstallOwnerAmbiguous(params.candidate)) { + return undefined; + } + const installOwner = resolvePluginCandidateInstallOwner(params.candidate); + if (installOwner) { + return Object.hasOwn(params.installRecords, installOwner) ? installOwner : undefined; + } + return undefined; +} + function matchesInstalledPluginRecord(params: { pluginId: string; candidate: PluginCandidate; @@ -790,7 +810,8 @@ function matchesInstalledPluginRecord(params: { if (params.candidate.origin !== "global" && params.candidate.origin !== "config") { return false; } - const record = params.installRecords[params.pluginId]; + const installOwner = resolveCandidateInstallOwner(params); + const record = installOwner ? params.installRecords[installOwner] : undefined; if (!record) { return false; } @@ -845,7 +866,9 @@ function isTrustedOfficialPluginInstall(params: { env: NodeJS.ProcessEnv; installRecords: Record; }): boolean { + const installOwner = resolveCandidateInstallOwner(params); if ( + !installOwner || (params.candidate.origin !== "global" && params.candidate.origin !== "config") || !matchesInstalledPluginRecord({ pluginId: params.pluginId, @@ -862,18 +885,18 @@ function isTrustedOfficialPluginInstall(params: { return false; } const catalogEntry = getOfficialExternalPluginCatalogEntryForPackage(packageName); - if (!catalogEntry || resolveOfficialExternalPluginId(catalogEntry) !== params.pluginId) { + if (!catalogEntry || resolveOfficialExternalPluginId(catalogEntry) !== installOwner) { return false; } const officialInstall = resolveOfficialExternalPluginInstall(catalogEntry); - const installRecord = params.installRecords[params.pluginId]; + const installRecord = params.installRecords[installOwner]; if (!installRecord) { return false; } const officialClawHubInstall = installRecord.source === "clawhub" ? resolveTrustedSourceLinkedOfficialClawHubInstall({ - pluginId: params.pluginId, + pluginId: installOwner, record: installRecord, }) : undefined; @@ -1190,7 +1213,11 @@ export function loadPluginManifestRegistryCore( ? { bundledChannelConfigCollector: params.bundledChannelConfigCollector } : {}), }); - + recordPluginManifestInstallOwner( + record, + resolvePluginCandidateInstallOwner(candidate), + isPluginCandidateInstallOwnerAmbiguous(candidate), + ); const existing = seenIds.get(effectivePluginId); if (existing) { // Check whether both candidates point to the same physical directory diff --git a/src/plugins/marketplace.ts b/src/plugins/marketplace.ts index 3dbe6857ace1..830689416528 100644 --- a/src/plugins/marketplace.ts +++ b/src/plugins/marketplace.ts @@ -19,6 +19,7 @@ import type { InstallPolicySource } from "../security/install-policy.js"; import { resolveUserPath } from "../utils.js"; import { isImmutableGitCommitRef } from "./git-install.js"; import type { InstallSafetyOverrides } from "./install-security-scan.js"; +import { copyPluginInstallTransactionRequest } from "./install-transaction.js"; import { installPluginFromPath, type InstallPluginResult } from "./install.js"; const DEFAULT_GIT_TIMEOUT_MS = 120_000; @@ -1326,31 +1327,33 @@ export async function installPluginFromMarketplace( } installCleanup = resolved.cleanup; - const result = await installPluginFromPath({ - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - config: params.config, - path: resolved.path, - logger: params.logger, - mode: params.mode, - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - dryRun: params.dryRun, - expectedPluginId: params.expectedPluginId, - installPolicyRequest: { - kind: marketplaceInstallPolicyRequestKind({ - marketplaceOrigin: loaded.marketplace.origin, - resolvedPath: resolved.path, - source: entry.source, - }), - requestedSpecifier: `${entry.name}@${params.marketplace}`, - source: marketplaceInstallPolicySource({ - marketplaceOrigin: loaded.marketplace.origin, - marketplaceRef: loaded.marketplace.remoteRef, - resolvedPath: resolved.path, - source: entry.source, - }), - }, - }); + const result = await installPluginFromPath( + copyPluginInstallTransactionRequest(params, { + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + config: params.config, + path: resolved.path, + logger: params.logger, + mode: params.mode, + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + dryRun: params.dryRun, + expectedPluginId: params.expectedPluginId, + installPolicyRequest: { + kind: marketplaceInstallPolicyRequestKind({ + marketplaceOrigin: loaded.marketplace.origin, + resolvedPath: resolved.path, + source: entry.source, + }), + requestedSpecifier: `${entry.name}@${params.marketplace}`, + source: marketplaceInstallPolicySource({ + marketplaceOrigin: loaded.marketplace.origin, + marketplaceRef: loaded.marketplace.remoteRef, + resolvedPath: resolved.path, + source: entry.source, + }), + }, + }), + ); if (!result.ok) { return result; } diff --git a/src/plugins/plugin-package-update.test.ts b/src/plugins/plugin-package-update.test.ts new file mode 100644 index 000000000000..efc3127ad622 --- /dev/null +++ b/src/plugins/plugin-package-update.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, it } from "vitest"; +import type { OpenClawConfig } from "../config/types.openclaw.js"; +import { recordInstalledPluginIndexInstallOwner } from "./installed-plugin-index-install-owner.js"; +import type { InstalledPluginIndex, InstalledPluginIndexRecord } from "./installed-plugin-index.js"; +import { + capturePluginPackageUpdateSnapshot, + pluginPackageUpdateMayMutateConfig, + reconcilePluginPackageUpdateConfig, +} from "./plugin-package-update.js"; + +function record( + pluginId: string, + rootDir: string, + contributions: { channels?: string[]; channelConfigs?: string[] } = {}, +): InstalledPluginIndexRecord { + return recordInstalledPluginIndexInstallOwner( + { + pluginId, + manifestPath: `${rootDir}/openclaw.plugin.json`, + manifestHash: pluginId, + source: `${rootDir}/${pluginId.split("/").at(-1)}.js`, + rootDir, + origin: "global", + enabled: true, + startup: { sidecar: false, memory: false, agentHarnesses: [] }, + contributions: { + channels: contributions.channels ?? [], + channelConfigs: contributions.channelConfigs ?? [], + providers: [], + modelCatalogProviders: [], + modelSupportPrefixes: [], + modelSupportPatterns: [], + autoEnableProviderIds: [], + commandAliases: [], + contracts: {}, + }, + compat: [], + }, + "pack", + ); +} + +function index(rootDir: string, plugins: InstalledPluginIndexRecord[]): InstalledPluginIndex { + return { + version: 1, + hostContractVersion: "test", + compatRegistryVersion: "test", + migrationVersion: 1, + policyHash: "test", + generatedAtMs: 1, + installRecords: { + pack: { source: "npm", installPath: rootDir, spec: "@openclaw/pack@latest" }, + }, + plugins, + diagnostics: [], + }; +} + +describe("plugin package update policy reconciliation", () => { + it("removes retired child policy while preserving retained, new, and unrelated state", () => { + const beforeRoot = "/packages/pack-v1"; + const afterRoot = "/packages/pack-v2"; + const before = index(beforeRoot, [ + record("pack/one", beforeRoot, { channels: ["shared"] }), + record("pack/two", beforeRoot, { channels: ["two-channel", "shared"] }), + record("pack/old", beforeRoot, { channelConfigs: ["old-config"] }), + ]); + const after = index(afterRoot, [ + record("pack/one", afterRoot, { channels: ["shared"] }), + record("pack/renamed", afterRoot), + ]); + const snapshot = capturePluginPackageUpdateSnapshot({ + index: before, + installOwners: ["pack"], + }); + expect(snapshot.ok).toBe(true); + if (!snapshot.ok) { + throw new Error(snapshot.error); + } + const config: OpenClawConfig = { + plugins: { + allow: ["pack/one", "pack/two", "pack/old", "other"], + deny: ["pack/two", "pack/old", "other-denied"], + entries: { + "pack/one": { enabled: true }, + "pack/two": { enabled: false }, + "pack/old": { enabled: true }, + other: { enabled: true }, + }, + load: { + paths: [`${beforeRoot}/two.js`, `${beforeRoot}/old.js`, "/plugins/unrelated.js"], + }, + slots: { memory: "pack/two", contextEngine: "pack/old" }, + }, + channels: { + "two-channel": { enabled: true }, + "old-config": { enabled: true }, + shared: { enabled: true }, + discord: { enabled: true }, + }, + }; + + const result = reconcilePluginPackageUpdateConfig({ + config, + beforeIndex: before, + afterIndex: after, + snapshot: snapshot.value, + }); + + expect(result.ok).toBe(true); + if (!result.ok) { + throw new Error(result.error); + } + expect(result.config.plugins).toEqual({ + allow: ["pack/one", "other"], + deny: ["other-denied"], + entries: { "pack/one": { enabled: true }, other: { enabled: true } }, + load: { paths: ["/plugins/unrelated.js"] }, + slots: { memory: "memory-core", contextEngine: "legacy" }, + }); + expect(result.config.channels).toEqual({ + shared: { enabled: true }, + discord: { enabled: true }, + }); + }); + + it("fails closed when the replacement package has no authoritative child rows", () => { + const before = index("/packages/pack-v1", [record("pack/one", "/packages/pack-v1")]); + const snapshot = capturePluginPackageUpdateSnapshot({ + index: before, + installOwners: ["pack"], + }); + expect(snapshot.ok).toBe(true); + if (!snapshot.ok) { + throw new Error(snapshot.error); + } + const result = reconcilePluginPackageUpdateConfig({ + config: { plugins: { entries: { "pack/one": { enabled: true } } } }, + beforeIndex: before, + afterIndex: index("/packages/pack-v2", []), + snapshot: snapshot.value, + }); + expect(result).toMatchObject({ ok: false }); + }); + + it("detects exact child load-path cleanup before an update starts", () => { + const rootDir = "/packages/pack-v1"; + const before = index(rootDir, [record("pack/one", rootDir)]); + const snapshot = capturePluginPackageUpdateSnapshot({ + index: before, + installOwners: ["pack"], + }); + expect(snapshot.ok).toBe(true); + if (!snapshot.ok) { + throw new Error(snapshot.error); + } + expect( + pluginPackageUpdateMayMutateConfig({ + config: { plugins: { load: { paths: [`${rootDir}/one.js`] } } }, + index: before, + snapshot: snapshot.value, + }), + ).toBe(true); + }); +}); diff --git a/src/plugins/plugin-package-update.ts b/src/plugins/plugin-package-update.ts new file mode 100644 index 000000000000..3c47255f8f7d --- /dev/null +++ b/src/plugins/plugin-package-update.ts @@ -0,0 +1,128 @@ +import type { OpenClawConfig } from "../config/types.openclaw.js"; +import type { InstalledPluginIndex } from "./installed-plugin-index.js"; +import { + resolveInstalledPluginPackageOwnership, + type InstalledPluginPackageOwnership, +} from "./installed-plugin-package-ownership.js"; +import { + hasMatchingPluginLoadPath, + removePluginRuntimePolicyFromConfig, +} from "./uninstall-package-config.js"; + +type PluginPackageUpdateSnapshot = ReadonlyMap; + +export function capturePluginPackageUpdateSnapshot(params: { + index: InstalledPluginIndex; + installOwners: readonly string[]; + env?: NodeJS.ProcessEnv; +}): { ok: true; value: PluginPackageUpdateSnapshot } | { ok: false; error: string } { + const snapshot = new Map(); + for (const installOwner of new Set(params.installOwners)) { + const ownership = resolveInstalledPluginPackageOwnership( + params.index, + installOwner, + params.env, + ); + if (!ownership.ok) { + return ownership; + } + snapshot.set(installOwner, ownership.value); + } + return { ok: true, value: snapshot }; +} + +function contributionKeys( + index: InstalledPluginIndex, + pluginIds: ReadonlySet, +): Set { + const keys = new Set(); + for (const plugin of index.plugins) { + if (!pluginIds.has(plugin.pluginId)) { + continue; + } + for (const key of [ + ...(plugin.contributions?.channels ?? []), + ...(plugin.contributions?.channelConfigs ?? []), + ]) { + keys.add(key); + } + } + return keys; +} + +/** Reconcile policy for children removed by a package update. */ +export function reconcilePluginPackageUpdateConfig(params: { + config: OpenClawConfig; + beforeIndex: InstalledPluginIndex; + afterIndex: InstalledPluginIndex; + snapshot: PluginPackageUpdateSnapshot; + installOwnerMigrations?: Readonly>; + env?: NodeJS.ProcessEnv; +}): { ok: true; config: OpenClawConfig } | { ok: false; error: string } { + let config = params.config; + for (const [installOwner, before] of params.snapshot) { + const nextInstallOwner = params.installOwnerMigrations?.[installOwner] ?? installOwner; + const after = resolveInstalledPluginPackageOwnership( + params.afterIndex, + nextInstallOwner, + params.env, + ); + if (!after.ok) { + return after; + } + const afterPluginIds = new Set(after.value.pluginIds); + const removedPluginIds = before.pluginIds.filter((pluginId) => !afterPluginIds.has(pluginId)); + if (removedPluginIds.length === 0) { + continue; + } + const retainedContributionKeys = contributionKeys(params.afterIndex, afterPluginIds); + for (const pluginId of removedPluginIds) { + const oldRecord = params.beforeIndex.plugins.find((plugin) => plugin.pluginId === pluginId); + const channelIds = [ + ...(oldRecord?.contributions?.channels ?? []), + ...(oldRecord?.contributions?.channelConfigs ?? []), + ].filter((channelId) => !retainedContributionKeys.has(channelId)); + config = removePluginRuntimePolicyFromConfig(config, pluginId, { + channelIds, + loadPaths: oldRecord?.source ? [oldRecord.source] : [], + }).config; + } + } + return { ok: true, config }; +} + +export function pluginPackageUpdateMayMutateConfig(params: { + config: OpenClawConfig; + index: InstalledPluginIndex; + snapshot: PluginPackageUpdateSnapshot; +}): boolean { + const plugins = params.config.plugins; + const channels = params.config.channels as Record | undefined; + for (const ownership of params.snapshot.values()) { + const pluginIds = new Set(ownership.pluginIds); + const ownedSources = params.index.plugins + .filter((plugin) => pluginIds.has(plugin.pluginId) && plugin.source) + .map((plugin) => plugin.source!); + if (hasMatchingPluginLoadPath(params.config, ownedSources)) { + return true; + } + for (const pluginId of ownership.pluginIds) { + if ( + plugins?.allow?.includes(pluginId) || + plugins?.deny?.includes(pluginId) || + Object.hasOwn(plugins?.entries ?? {}, pluginId) || + plugins?.slots?.memory === pluginId || + plugins?.slots?.contextEngine === pluginId + ) { + return true; + } + } + if ( + channels && + [...contributionKeys(params.index, pluginIds)].some((key) => Object.hasOwn(channels, key)) + ) { + return true; + } + } + return false; +} diff --git a/src/plugins/plugin-registry-snapshot.test.ts b/src/plugins/plugin-registry-snapshot.test.ts index 4153cac665fd..ee11d73d95be 100644 --- a/src/plugins/plugin-registry-snapshot.test.ts +++ b/src/plugins/plugin-registry-snapshot.test.ts @@ -628,6 +628,38 @@ describe("loadPluginRegistrySnapshotWithMetadata", () => { expect(result.diagnostics).toStrictEqual([]); }); + it("keeps unrelated installed plugins usable beside a vanished package owner", () => { + const tempRoot = makeTempDir(); + const stateDir = path.join(tempRoot, "state"); + const demoDir = path.join(stateDir, "extensions", "demo"); + const goneDir = path.join(stateDir, "extensions", "gone"); + const env = { + ...createHermeticEnv(tempRoot), + OPENCLAW_DISABLE_BUNDLED_PLUGINS: "1", + OPENCLAW_STATE_DIR: stateDir, + }; + writePackagePlugin(demoDir, { pluginId: "demo" }); + const config = { + plugins: { + entries: { + demo: { enabled: true }, + gone: { enabled: true }, + }, + }, + }; + const installRecords = { + demo: { source: "path" as const, sourcePath: demoDir, installPath: demoDir }, + gone: { source: "path" as const, sourcePath: goneDir, installPath: goneDir }, + }; + const index = loadInstalledPluginIndex({ config, env, stateDir, installRecords }); + writePersistedInstalledPluginIndexSync(index, { stateDir }); + + const result = loadPluginRegistrySnapshotWithMetadata({ config, env, stateDir }); + + expect(result.source).toBe("persisted"); + expect(result.snapshot.plugins.map((plugin) => plugin.pluginId)).toContain("demo"); + }); + it("keeps persisted manifestless Claude bundles on the fast path", () => { const tempRoot = makeTempDir(); const rootDir = path.join(tempRoot, "workspace"); diff --git a/src/plugins/plugin-registry-snapshot.ts b/src/plugins/plugin-registry-snapshot.ts index c4e9abac9a52..481a69376c63 100644 --- a/src/plugins/plugin-registry-snapshot.ts +++ b/src/plugins/plugin-registry-snapshot.ts @@ -33,6 +33,7 @@ import { type LoadInstalledPluginIndexParams, type RefreshInstalledPluginIndexParams, } from "./installed-plugin-index.js"; +import { hasMissingInstalledPluginOwnerMetadata } from "./installed-plugin-package-ownership.js"; import { loadPluginManifestRegistryCore, type PluginManifestRegistry, @@ -386,10 +387,10 @@ function hasRecoveredInstallRecordsMissingFromPersistedIndex( ? { filePath: params.pluginIndexFilePath } : {}), }); - const pluginIds = new Set(index.plugins.map((plugin) => plugin.pluginId)); - return Object.keys(installRecords).some( - (pluginId) => !index.installRecords?.[pluginId] || !pluginIds.has(pluginId), - ); + // A durable owner can outlive removed package bytes. Lifecycle mutations fail + // closed without child rows; registry recovery only needs to detect records + // that are absent from the persisted top-level ledger. + return Object.keys(installRecords).some((pluginId) => !index.installRecords?.[pluginId]); } function requiresDerivedRegistryValidation( @@ -405,6 +406,7 @@ function requiresDerivedRegistryValidation( params.installRecords !== undefined || normalizePluginsConfig(params.config?.plugins).loadPaths.length > 0 || hasMissingConfigPathActivationMetadata(index) || + hasMissingInstalledPluginOwnerMetadata(index, env) || index.diagnostics.some(({ pluginId, source }) => Boolean(pluginId && source && path.isAbsolute(source) && !fs.existsSync(source)), ) || diff --git a/src/plugins/uninstall-config.ts b/src/plugins/uninstall-config.ts index 672dfe16a0a2..b69ac448730e 100644 --- a/src/plugins/uninstall-config.ts +++ b/src/plugins/uninstall-config.ts @@ -1,52 +1,24 @@ // Pure plugin config cleanup shared by doctor repair and full uninstall flows. -import { realpathSync } from "node:fs"; -import path from "node:path"; import type { OpenClawConfig } from "../config/types.openclaw.js"; -import { resetPluginSlotsToDefaults } from "./slots.js"; +import { + isUninstallPathInsideOrEqualInternal, + removePluginInstallOwnerFromConfig, + removePluginRuntimePolicyFromConfig, + resolveComparableUninstallPathInternal, + resolveUninstallChannelConfigKeysInternal, +} from "./uninstall-package-config.js"; +import type { PluginConfigUninstallActions } from "./uninstall-package-config.js"; -export type PluginConfigUninstallActions = { - entry: boolean; - install: boolean; - allowlist: boolean; - denylist: boolean; - loadPath: boolean; - memorySlot: boolean; - contextEngineSlot: boolean; - channelConfig: boolean; -}; - -const SHARED_CHANNEL_CONFIG_KEYS = new Set(["defaults", "modelByChannel"]); - -function createEmptyConfigUninstallActions(): PluginConfigUninstallActions { - return { - entry: false, - install: false, - allowlist: false, - denylist: false, - loadPath: false, - memorySlot: false, - contextEngineSlot: false, - channelConfig: false, - }; -} +export type { PluginConfigUninstallActions } from "./uninstall-package-config.js"; /** Resolve a path through existing ancestors while preserving missing targets. */ export function resolveComparableUninstallPath(value: string): string { - const resolved = path.resolve(value); - try { - return realpathSync(resolved); - } catch { - return resolved; - } + return resolveComparableUninstallPathInternal(value); } /** Check whether a managed uninstall target stays inside its owning root. */ export function isUninstallPathInsideOrEqual(parent: string, child: string): boolean { - const relative = path.relative( - resolveComparableUninstallPath(parent), - resolveComparableUninstallPath(child), - ); - return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); + return isUninstallPathInsideOrEqualInternal(parent, child); } /** Resolve channel config keys owned by a plugin during uninstall. */ @@ -54,24 +26,20 @@ export function resolveUninstallChannelConfigKeys( pluginId: string, opts?: { channelIds?: string[] }, ): string[] { - const rawKeys = opts?.channelIds ?? [pluginId]; - const seen = new Set(); - const keys: string[] = []; - for (const key of rawKeys) { - if (SHARED_CHANNEL_CONFIG_KEYS.has(key) || seen.has(key)) { - continue; - } - seen.add(key); - keys.push(key); - } - return keys; + return resolveUninstallChannelConfigKeysInternal(pluginId, opts); } -function loadPathMatchesInstallPath(loadPath: string, installPath: string): boolean { - return ( - loadPath === installPath || - resolveComparableUninstallPath(loadPath) === resolveComparableUninstallPath(installPath) - ); +function mergeUninstallActions( + left: PluginConfigUninstallActions, + right: PluginConfigUninstallActions, +): PluginConfigUninstallActions { + return Object.fromEntries( + Object.keys(left).map((key) => [ + key, + left[key as keyof PluginConfigUninstallActions] || + right[key as keyof PluginConfigUninstallActions], + ]), + ) as PluginConfigUninstallActions; } /** Remove plugin references from config without loading uninstall process/runtime dependencies. */ @@ -80,113 +48,10 @@ export function removePluginFromConfig( pluginId: string, opts?: { channelIds?: string[] }, ): { config: OpenClawConfig; actions: PluginConfigUninstallActions } { - const actions = createEmptyConfigUninstallActions(); - const pluginsConfig = cfg.plugins ?? {}; - - let entries = pluginsConfig.entries; - if (entries && Object.hasOwn(entries, pluginId)) { - const { [pluginId]: _, ...rest } = entries; - entries = Object.keys(rest).length > 0 ? rest : undefined; - actions.entry = true; - } - - let installs = pluginsConfig.installs; - const hasInstallRecord = Object.hasOwn(installs ?? {}, pluginId); - const installRecord = hasInstallRecord ? installs?.[pluginId] : undefined; - if (installs && hasInstallRecord) { - const { [pluginId]: _, ...rest } = installs; - installs = Object.keys(rest).length > 0 ? rest : undefined; - actions.install = true; - } - - let allow = pluginsConfig.allow; - if (Array.isArray(allow) && allow.includes(pluginId)) { - allow = allow.filter((id) => id !== pluginId); - allow = allow.length > 0 ? allow : undefined; - actions.allowlist = true; - } - - let deny = pluginsConfig.deny; - if (Array.isArray(deny) && deny.includes(pluginId)) { - deny = deny.filter((id) => id !== pluginId); - deny = deny.length > 0 ? deny : undefined; - actions.denylist = true; - } - - let load = pluginsConfig.load; - const trackedInstallPaths = [ - installRecord?.installPath, - installRecord?.source === "path" ? installRecord.sourcePath : undefined, - ].filter((value): value is string => Boolean(value)); - if (trackedInstallPaths.length > 0) { - const loadPaths = load?.paths; - if ( - Array.isArray(loadPaths) && - loadPaths.some((candidate) => - trackedInstallPaths.some((installPath) => - loadPathMatchesInstallPath(candidate, installPath), - ), - ) - ) { - const nextLoadPaths = loadPaths.filter( - (candidate) => - !trackedInstallPaths.some((installPath) => - loadPathMatchesInstallPath(candidate, installPath), - ), - ); - load = nextLoadPaths.length > 0 ? { ...load, paths: nextLoadPaths } : undefined; - actions.loadPath = true; - } - } - - let slots = pluginsConfig.slots; - if (slots?.memory === pluginId) { - actions.memorySlot = true; - } - if (slots?.contextEngine === pluginId) { - actions.contextEngineSlot = true; - } - slots = resetPluginSlotsToDefaults(slots, pluginId); - if (slots && Object.keys(slots).length === 0) { - slots = undefined; - } - - const cleanedPlugins = { - ...pluginsConfig, - entries, - installs, - allow, - deny, - load, - slots, - }; - for (const key of ["entries", "installs", "allow", "deny", "load", "slots"] as const) { - if (cleanedPlugins[key] === undefined) { - delete cleanedPlugins[key]; - } - } - - let channels = cfg.channels as Record | undefined; - if (hasInstallRecord && channels) { - for (const key of resolveUninstallChannelConfigKeys(pluginId, opts)) { - if (!Object.hasOwn(channels, key)) { - continue; - } - const { [key]: _removed, ...rest } = channels; - channels = Object.keys(rest).length > 0 ? rest : undefined; - actions.channelConfig = true; - if (!channels) { - break; - } - } - } - - return { - config: { - ...cfg, - plugins: Object.keys(cleanedPlugins).length > 0 ? cleanedPlugins : undefined, - channels: channels as OpenClawConfig["channels"], - }, - actions, - }; + const hasInstallRecord = Object.hasOwn(cfg.plugins?.installs ?? {}, pluginId); + const policy = removePluginRuntimePolicyFromConfig(cfg, pluginId, { + ...(hasInstallRecord ? opts : { channelIds: [] }), + }); + const owner = removePluginInstallOwnerFromConfig(policy.config, pluginId); + return { config: owner.config, actions: mergeUninstallActions(policy.actions, owner.actions) }; } diff --git a/src/plugins/uninstall-package-config.ts b/src/plugins/uninstall-package-config.ts new file mode 100644 index 000000000000..2d832e378336 --- /dev/null +++ b/src/plugins/uninstall-package-config.ts @@ -0,0 +1,227 @@ +import { realpathSync } from "node:fs"; +import path from "node:path"; +import type { OpenClawConfig } from "../config/types.openclaw.js"; +import { resetPluginSlotsToDefaults } from "./slots.js"; + +export type PluginConfigUninstallActions = { + entry: boolean; + install: boolean; + allowlist: boolean; + denylist: boolean; + loadPath: boolean; + memorySlot: boolean; + contextEngineSlot: boolean; + channelConfig: boolean; +}; + +const SHARED_CHANNEL_CONFIG_KEYS = new Set(["defaults", "modelByChannel"]); + +function createEmptyConfigUninstallActions(): PluginConfigUninstallActions { + return { + entry: false, + install: false, + allowlist: false, + denylist: false, + loadPath: false, + memorySlot: false, + contextEngineSlot: false, + channelConfig: false, + }; +} + +export function resolveComparableUninstallPathInternal(value: string): string { + const resolved = path.resolve(value); + try { + return realpathSync(resolved); + } catch { + return resolved; + } +} + +export function isUninstallPathInsideOrEqualInternal(parent: string, child: string): boolean { + const relative = path.relative( + resolveComparableUninstallPathInternal(parent), + resolveComparableUninstallPathInternal(child), + ); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +} + +export function resolveUninstallChannelConfigKeysInternal( + pluginId: string, + opts?: { channelIds?: string[] }, +): string[] { + const rawKeys = opts?.channelIds ?? [pluginId]; + const seen = new Set(); + const keys: string[] = []; + for (const key of rawKeys) { + if (SHARED_CHANNEL_CONFIG_KEYS.has(key) || seen.has(key)) { + continue; + } + seen.add(key); + keys.push(key); + } + return keys; +} + +function loadPathMatchesInstallPath(loadPath: string, installPath: string): boolean { + return ( + loadPath === installPath || + resolveComparableUninstallPathInternal(loadPath) === + resolveComparableUninstallPathInternal(installPath) + ); +} + +export function hasMatchingPluginLoadPath( + config: OpenClawConfig, + ownedPaths: readonly string[], +): boolean { + return Boolean( + config.plugins?.load?.paths?.some((candidate) => + ownedPaths.some((ownedPath) => loadPathMatchesInstallPath(candidate, ownedPath)), + ), + ); +} + +function removeMatchingLoadPaths( + load: NonNullable["load"], + ownedPaths: readonly string[], +): { load: NonNullable["load"] | undefined; changed: boolean } { + const loadPaths = load?.paths; + if ( + ownedPaths.length === 0 || + !Array.isArray(loadPaths) || + !loadPaths.some((candidate) => + ownedPaths.some((ownedPath) => loadPathMatchesInstallPath(candidate, ownedPath)), + ) + ) { + return { load, changed: false }; + } + const nextLoadPaths = loadPaths.filter( + (candidate) => + !ownedPaths.some((ownedPath) => loadPathMatchesInstallPath(candidate, ownedPath)), + ); + return { + load: nextLoadPaths.length > 0 ? { ...load, paths: nextLoadPaths } : undefined, + changed: true, + }; +} + +export function removePluginRuntimePolicyFromConfig( + cfg: OpenClawConfig, + pluginId: string, + opts?: { channelIds?: string[]; loadPaths?: string[] }, +): { config: OpenClawConfig; actions: PluginConfigUninstallActions } { + const actions = createEmptyConfigUninstallActions(); + const pluginsConfig = cfg.plugins ?? {}; + + let entries = pluginsConfig.entries; + if (entries && Object.hasOwn(entries, pluginId)) { + const { [pluginId]: _, ...rest } = entries; + entries = Object.keys(rest).length > 0 ? rest : undefined; + actions.entry = true; + } + + let allow = pluginsConfig.allow; + if (Array.isArray(allow) && allow.includes(pluginId)) { + allow = allow.filter((id) => id !== pluginId); + allow = allow.length > 0 ? allow : undefined; + actions.allowlist = true; + } + + let deny = pluginsConfig.deny; + if (Array.isArray(deny) && deny.includes(pluginId)) { + deny = deny.filter((id) => id !== pluginId); + deny = deny.length > 0 ? deny : undefined; + actions.denylist = true; + } + + const loadResult = removeMatchingLoadPaths(pluginsConfig.load, opts?.loadPaths ?? []); + actions.loadPath = loadResult.changed; + + let slots = pluginsConfig.slots; + if (slots?.memory === pluginId) { + actions.memorySlot = true; + } + if (slots?.contextEngine === pluginId) { + actions.contextEngineSlot = true; + } + slots = resetPluginSlotsToDefaults(slots, pluginId); + if (slots && Object.keys(slots).length === 0) { + slots = undefined; + } + + const cleanedPlugins = { + ...pluginsConfig, + entries, + allow, + deny, + load: loadResult.load, + slots, + }; + for (const key of ["entries", "allow", "deny", "load", "slots"] as const) { + if (cleanedPlugins[key] === undefined) { + delete cleanedPlugins[key]; + } + } + + let channels = cfg.channels as Record | undefined; + for (const key of resolveUninstallChannelConfigKeysInternal(pluginId, opts)) { + if (!channels || !Object.hasOwn(channels, key)) { + continue; + } + const { [key]: _removed, ...rest } = channels; + channels = Object.keys(rest).length > 0 ? rest : undefined; + actions.channelConfig = true; + } + + if (!Object.values(actions).some(Boolean)) { + return { config: cfg, actions }; + } + return { + config: { + ...cfg, + plugins: Object.keys(cleanedPlugins).length > 0 ? cleanedPlugins : undefined, + channels: channels as OpenClawConfig["channels"], + }, + actions, + }; +} + +export function removePluginInstallOwnerFromConfig( + cfg: OpenClawConfig, + installOwner: string, +): { config: OpenClawConfig; actions: PluginConfigUninstallActions } { + const actions = createEmptyConfigUninstallActions(); + const pluginsConfig = cfg.plugins ?? {}; + let installs = pluginsConfig.installs; + const installRecord = Object.hasOwn(installs ?? {}, installOwner) + ? installs?.[installOwner] + : undefined; + if (installs && installRecord) { + const { [installOwner]: _, ...rest } = installs; + installs = Object.keys(rest).length > 0 ? rest : undefined; + actions.install = true; + } + const trackedPaths = [ + installRecord?.installPath, + installRecord?.source === "path" ? installRecord.sourcePath : undefined, + ].filter((value): value is string => Boolean(value)); + const loadResult = removeMatchingLoadPaths(pluginsConfig.load, trackedPaths); + actions.loadPath = loadResult.changed; + const cleanedPlugins = { ...pluginsConfig, installs, load: loadResult.load }; + for (const key of ["installs", "load"] as const) { + if (cleanedPlugins[key] === undefined) { + delete cleanedPlugins[key]; + } + } + if (!Object.values(actions).some(Boolean)) { + return { config: cfg, actions }; + } + return { + config: { + ...cfg, + plugins: Object.keys(cleanedPlugins).length > 0 ? cleanedPlugins : undefined, + }, + actions, + }; +} diff --git a/src/plugins/uninstall-package-plan.ts b/src/plugins/uninstall-package-plan.ts new file mode 100644 index 000000000000..683637326b4f --- /dev/null +++ b/src/plugins/uninstall-package-plan.ts @@ -0,0 +1,48 @@ +import type { OpenClawConfig } from "../config/types.openclaw.js"; + +const PLUGIN_PACKAGE_UNINSTALL_PLAN = Symbol.for("openclaw.pluginPackageUninstallPlan"); + +type PluginPackageUninstallPlanMetadata = { + runtimePluginIds: readonly string[]; + runtimeLoadPaths?: readonly string[]; +}; + +export function recordPluginPackageUninstallPlan( + params: T, + metadata: PluginPackageUninstallPlanMetadata, +): T { + Object.defineProperty(params, PLUGIN_PACKAGE_UNINSTALL_PLAN, { + configurable: false, + enumerable: true, + value: metadata, + }); + return params; +} + +export function resolvePluginPackageUninstallPlan( + params: object, +): PluginPackageUninstallPlanMetadata | undefined { + return (params as { [PLUGIN_PACKAGE_UNINSTALL_PLAN]?: PluginPackageUninstallPlanMetadata })[ + PLUGIN_PACKAGE_UNINSTALL_PLAN + ]; +} + +export function prepareConfigForPendingPluginDirectoryRemovalSet( + config: OpenClawConfig, + pluginIds: readonly string[], +): OpenClawConfig { + const entries = { ...config.plugins?.entries }; + for (const entryId of new Set(pluginIds)) { + entries[entryId] = { + ...entries[entryId], + enabled: false, + }; + } + return { + ...config, + plugins: { + ...config.plugins, + entries, + }, + }; +} diff --git a/src/plugins/uninstall.test.ts b/src/plugins/uninstall.test.ts index 2065ab145033..d03a67345295 100644 --- a/src/plugins/uninstall.test.ts +++ b/src/plugins/uninstall.test.ts @@ -13,6 +13,10 @@ import { } from "./test-helpers/fs-fixtures.js"; import { removePluginFromConfig } from "./uninstall-config.js"; import { pruneManagedNpmPeerDependenciesAfterUninstall } from "./uninstall-managed-npm.js"; +import { + prepareConfigForPendingPluginDirectoryRemovalSet, + recordPluginPackageUninstallPlan, +} from "./uninstall-package-plan.js"; import { applyPluginUninstallDirectoryRemoval, planPluginUninstall, @@ -28,8 +32,19 @@ vi.mock("../process/exec.js", () => ({ type PluginConfig = NonNullable; type PluginInstallRecord = NonNullable[string]; -async function uninstallPlugin(params: Parameters[0]) { - const plan = planPluginUninstall(params); +async function uninstallPlugin( + params: Parameters[0] & { + runtimePluginIds?: readonly string[]; + runtimeLoadPaths?: readonly string[]; + }, +) { + const { runtimePluginIds, runtimeLoadPaths, ...planParams } = params; + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan(planParams, { + runtimePluginIds: runtimePluginIds ?? [params.pluginId], + ...(runtimeLoadPaths ? { runtimeLoadPaths } : {}), + }), + ); if (!plan.ok) { return plan; } @@ -249,6 +264,26 @@ function createSingleNpmInstallConfig(installPath: string): OpenClawConfig { }); } +it("stages only runtime child entries while a package directory removal is pending", () => { + const staged = prepareConfigForPendingPluginDirectoryRemovalSet( + { + plugins: { + entries: { + "pack/one": { enabled: true }, + "pack/two": { enabled: true }, + }, + }, + }, + ["pack/one", "pack/two"], + ); + + expect(staged.plugins?.entries).toEqual({ + "pack/one": { enabled: false }, + "pack/two": { enabled: false }, + }); + expect(staged.plugins?.entries).not.toHaveProperty("pack"); +}); + async function createPluginDirFixture(baseDir: string, pluginId = "my-plugin") { const pluginDir = path.join(baseDir, pluginId); await fs.mkdir(pluginDir, { recursive: true }); @@ -315,6 +350,53 @@ describe("resolveUninstallChannelConfigKeys", () => { }); }); +describe("planPluginUninstall package ownership", () => { + it("removes every owned child policy while planning one owner install removal", () => { + const result = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: { + plugins: { + allow: ["pack/one", "pack/two", "other"], + deny: ["pack/two"], + entries: { + "pack/one": { enabled: true }, + "pack/two": { enabled: false }, + other: { enabled: true }, + }, + installs: { + pack: { source: "path", installPath: "/managed/pack" }, + }, + slots: { memory: "pack/two" }, + }, + }, + pluginId: "pack", + deleteFiles: false, + }, + { runtimePluginIds: ["pack/one", "pack/two"] }, + ), + ); + + expect(result.ok).toBe(true); + if (!result.ok) { + throw new Error(result.error); + } + expect(result.directoryRemoval).toBeNull(); + expect(result.config.plugins).toEqual({ + allow: ["other"], + entries: { other: { enabled: true } }, + slots: { memory: "memory-core" }, + }); + expect(result.actions).toMatchObject({ + entry: true, + install: true, + allowlist: true, + denylist: true, + memorySlot: true, + }); + }); +}); + describe("removePluginFromConfig", () => { it("removes plugin from entries", () => { const config = createPluginConfig({ @@ -1068,12 +1150,12 @@ describe("uninstallPlugin", () => { baseDir: tempDir, }); - const plan = planPluginUninstall({ - config, - pluginId, - deleteFiles: true, - extensionsDir, - }); + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { config, pluginId, deleteFiles: true, extensionsDir }, + { runtimePluginIds: [pluginId] }, + ), + ); expect(plan.ok).toBe(true); if (!plan.ok) { @@ -1113,21 +1195,26 @@ describe("uninstallPlugin", () => { await fs.writeFile(path.join(pluginDir, "package.json"), "{}"); await fs.writeFile(path.join(hoistedDir, "package.json"), "{}"); - const plan = planPluginUninstall({ - config: createPluginConfig({ - entries: createSinglePluginEntries("openclaw-kitchen-sink-fixture"), - installs: { - "openclaw-kitchen-sink-fixture": { - source: "npm", - spec: "@openclaw/kitchen-sink@1.0.0", - installPath: pluginDir, - }, + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: createPluginConfig({ + entries: createSinglePluginEntries("openclaw-kitchen-sink-fixture"), + installs: { + "openclaw-kitchen-sink-fixture": { + source: "npm", + spec: "@openclaw/kitchen-sink@1.0.0", + installPath: pluginDir, + }, + }, + }), + pluginId: "openclaw-kitchen-sink-fixture", + deleteFiles: true, + extensionsDir, }, - }), - pluginId: "openclaw-kitchen-sink-fixture", - deleteFiles: true, - extensionsDir, - }); + { runtimePluginIds: ["openclaw-kitchen-sink-fixture"] }, + ), + ); expect(plan.ok).toBe(true); if (!plan.ok) { @@ -1178,21 +1265,26 @@ describe("uninstallPlugin", () => { await fs.writeFile(path.join(pluginDir, "package.json"), "{}"); await fs.writeFile(path.join(hoistedDir, "package.json"), "{}"); - const plan = planPluginUninstall({ - config: createPluginConfig({ - entries: createSinglePluginEntries("openclaw-kitchen-sink-fixture"), - installs: { - "openclaw-kitchen-sink-fixture": { - source: "npm", - spec: "@openclaw/kitchen-sink@1.0.0", - installPath: pluginDir, - }, + const plan = planPluginUninstall( + recordPluginPackageUninstallPlan( + { + config: createPluginConfig({ + entries: createSinglePluginEntries("openclaw-kitchen-sink-fixture"), + installs: { + "openclaw-kitchen-sink-fixture": { + source: "npm", + spec: "@openclaw/kitchen-sink@1.0.0", + installPath: pluginDir, + }, + }, + }), + pluginId: "openclaw-kitchen-sink-fixture", + deleteFiles: true, + extensionsDir, }, - }), - pluginId: "openclaw-kitchen-sink-fixture", - deleteFiles: true, - extensionsDir, - }); + { runtimePluginIds: ["openclaw-kitchen-sink-fixture"] }, + ), + ); expect(plan.ok).toBe(true); if (!plan.ok) { diff --git a/src/plugins/uninstall.ts b/src/plugins/uninstall.ts index fb7d3318c012..b53a5468798d 100644 --- a/src/plugins/uninstall.ts +++ b/src/plugins/uninstall.ts @@ -18,11 +18,15 @@ import { relinkOpenClawPeerDependenciesInManagedNpmRoot } from "./plugin-peer-li import { defaultSlotIdForKey } from "./slots.js"; import { isUninstallPathInsideOrEqual, - removePluginFromConfig, resolveComparableUninstallPath, type PluginConfigUninstallActions, } from "./uninstall-config.js"; import { pruneManagedNpmPeerDependenciesAfterUninstall } from "./uninstall-managed-npm.js"; +import { + removePluginInstallOwnerFromConfig, + removePluginRuntimePolicyFromConfig, +} from "./uninstall-package-config.js"; +import { resolvePluginPackageUninstallPlan } from "./uninstall-package-plan.js"; export { resolveUninstallChannelConfigKeys } from "./uninstall-config.js"; @@ -60,26 +64,6 @@ export function formatUninstallActionLabels(actions: UninstallActions): string[] ); } -/** Keep a staged plugin disabled until its managed directory is removed. */ -export function prepareConfigForPendingPluginDirectoryRemoval( - config: OpenClawConfig, - pluginId: string, -): OpenClawConfig { - return { - ...config, - plugins: { - ...config.plugins, - entries: { - ...config.plugins?.entries, - [pluginId]: { - ...config.plugins?.entries?.[pluginId], - enabled: false, - }, - }, - }, - }; -} - function hasUninstallAction(actions: PluginConfigUninstallActions): boolean { return Object.values(actions).some(Boolean); } @@ -321,6 +305,7 @@ function isLinkedPathInstallRecord(installRecord: PluginInstallRecord | undefine type UninstallPluginParams = { config: OpenClawConfig; + /** Package install-record key whose record and shared directory are removed once. */ pluginId: string; channelIds?: string[]; deleteFiles?: boolean; @@ -334,18 +319,43 @@ type UninstallPluginParams = { */ export function planPluginUninstall(params: UninstallPluginParams): PluginUninstallPlanResult { const { config, pluginId, channelIds, deleteFiles = true, extensionsDir } = params; + const packagePlan = resolvePluginPackageUninstallPlan(params); + const runtimePluginIds = packagePlan?.runtimePluginIds ?? [pluginId]; const entries = config.plugins?.entries ?? {}; const installs = config.plugins?.installs ?? {}; - const hasEntry = Object.hasOwn(entries, pluginId); + const hasEntry = runtimePluginIds.some((entryId) => Object.hasOwn(entries, entryId)); const hasInstall = Object.hasOwn(installs, pluginId); const installRecord = hasInstall ? installs[pluginId] : undefined; const isLinked = isLinkedPathInstallRecord(installRecord); - // Remove from config - const { config: newConfig, actions: configActions } = removePluginFromConfig(config, pluginId, { - channelIds, - }); + // Package lifecycle removes every child policy while the owner record/directory is handled once. + let newConfig = config; + const configActions: PluginConfigUninstallActions = { + entry: false, + install: false, + allowlist: false, + denylist: false, + loadPath: false, + memorySlot: false, + contextEngineSlot: false, + channelConfig: false, + }; + for (const configPluginId of new Set(runtimePluginIds)) { + const removal = removePluginRuntimePolicyFromConfig(newConfig, configPluginId, { + channelIds, + loadPaths: packagePlan?.runtimeLoadPaths ? [...packagePlan.runtimeLoadPaths] : undefined, + }); + newConfig = removal.config; + for (const key of Object.keys(configActions) as Array) { + configActions[key] ||= removal.actions[key]; + } + } + const ownerRemoval = removePluginInstallOwnerFromConfig(newConfig, pluginId); + newConfig = ownerRemoval.config; + for (const key of Object.keys(configActions) as Array) { + configActions[key] ||= ownerRemoval.actions[key]; + } if (!hasEntry && !hasInstall && !hasUninstallAction(configActions)) { return { ok: false, error: `Plugin not found: ${pluginId}` }; diff --git a/src/plugins/update-attempt.ts b/src/plugins/update-attempt.ts index 2bc7aa7428da..5baaa73ed772 100644 --- a/src/plugins/update-attempt.ts +++ b/src/plugins/update-attempt.ts @@ -4,6 +4,7 @@ import type { UpdateChannel } from "../infra/update-channels.js"; import { CLAWHUB_INSTALL_ERROR_CODE } from "./clawhub-error-codes.js"; import { installPluginFromClawHub, type ClawHubRiskAcknowledgementRequest } from "./clawhub.js"; import { installPluginFromGitSpec } from "./git-install.js"; +import { copyPluginInstallTransactionRequest } from "./install-transaction.js"; import { installPluginFromNpmSpec, PLUGIN_INSTALL_ERROR_CODE } from "./install.js"; import { installPluginFromMarketplace } from "./marketplace.js"; import { shouldFallbackClawHubBridgeToNpm } from "./update-config.js"; @@ -345,68 +346,78 @@ export async function runPluginUpdateAttempt(params: { const dryRunOption = params.dryRun ? { dryRun: true } : {}; const phase = params.dryRun ? "check" : "update"; const installNpmSpec = params.dryRun ? installPluginFromNpmSpec : params.installNpmSpecForUpdate; + const installParams = (value: T): T => + copyPluginInstallTransactionRequest(params, value); let result: PluginUpdateInstallResult; try { result = params.record.source === "npm" - ? await installNpmSpec({ - spec: params.effectiveSpec!, - config: params.config, - mode: "update", - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - ...dryRunOption, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, - expectedPluginId: params.pluginId, - expectedReplacementPluginId: params.expectedReplacementPluginId, - expectedIntegrity: params.expectedIntegrity, - onIntegrityDrift: createPluginUpdateIntegrityDriftHandler({ - pluginId: params.pluginId, - dryRun: params.dryRun, - logger: params.logger, - onIntegrityDrift: params.onIntegrityDrift, - }), - logger: params.logger, - }) - : params.record.source === "clawhub" - ? await installPluginFromClawHub({ - spec: params.effectiveSpec ?? `clawhub:${params.record.clawhubPackage!}`, + ? await installNpmSpec( + installParams({ + spec: params.effectiveSpec!, config: params.config, - baseUrl: params.record.clawhubUrl, mode: "update", extensionsDir: params.extensionsDir, timeoutMs: params.timeoutMs, ...dryRunOption, dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, expectedPluginId: params.pluginId, - ...params.clawHubRiskAcknowledgementOptions, + expectedReplacementPluginId: params.expectedReplacementPluginId, + expectedIntegrity: params.expectedIntegrity, + onIntegrityDrift: createPluginUpdateIntegrityDriftHandler({ + pluginId: params.pluginId, + dryRun: params.dryRun, + logger: params.logger, + onIntegrityDrift: params.onIntegrityDrift, + }), logger: params.logger, - }) + }), + ) + : params.record.source === "clawhub" + ? await installPluginFromClawHub( + installParams({ + spec: params.effectiveSpec ?? `clawhub:${params.record.clawhubPackage!}`, + config: params.config, + baseUrl: params.record.clawhubUrl, + mode: "update", + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + ...dryRunOption, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + expectedPluginId: params.pluginId, + ...params.clawHubRiskAcknowledgementOptions, + logger: params.logger, + }), + ) : params.record.source === "git" - ? await installPluginFromGitSpec({ - spec: params.effectiveSpec!, - config: params.config, - mode: "update", - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - ...dryRunOption, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - expectedPluginId: params.pluginId, - logger: params.logger, - }) - : await installPluginFromMarketplace({ - marketplace: params.record.marketplaceSource!, - plugin: params.record.marketplacePlugin!, - config: params.config, - mode: "update", - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - ...dryRunOption, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - expectedPluginId: params.pluginId, - logger: params.logger, - }); + ? await installPluginFromGitSpec( + installParams({ + spec: params.effectiveSpec!, + config: params.config, + mode: "update", + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + ...dryRunOption, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + expectedPluginId: params.pluginId, + logger: params.logger, + }), + ) + : await installPluginFromMarketplace( + installParams({ + marketplace: params.record.marketplaceSource!, + plugin: params.record.marketplacePlugin!, + config: params.config, + mode: "update", + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + ...dryRunOption, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + expectedPluginId: params.pluginId, + logger: params.logger, + }), + ); } catch (error) { return { kind: "exception", @@ -445,26 +456,28 @@ export async function runPluginUpdateAttempt(params: { fallbackSpec: params.npmSpecs.fallbackSpec, verb: params.dryRun ? "would use" : "used", }); - result = await installNpmSpec({ - spec: params.npmSpecs.fallbackSpec, - config: params.config, - mode: "update", - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - ...dryRunOption, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, - expectedPluginId: params.pluginId, - expectedReplacementPluginId: params.expectedReplacementPluginId, - expectedIntegrity: await params.getFallbackExpectedIntegrity(), - onIntegrityDrift: createPluginUpdateIntegrityDriftHandler({ - pluginId: params.pluginId, - dryRun: params.dryRun, + result = await installNpmSpec( + installParams({ + spec: params.npmSpecs.fallbackSpec, + config: params.config, + mode: "update", + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + ...dryRunOption, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + trustedSourceLinkedOfficialInstall: params.trustedSourceLinkedOfficialInstall, + expectedPluginId: params.pluginId, + expectedReplacementPluginId: params.expectedReplacementPluginId, + expectedIntegrity: await params.getFallbackExpectedIntegrity(), + onIntegrityDrift: createPluginUpdateIntegrityDriftHandler({ + pluginId: params.pluginId, + dryRun: params.dryRun, + logger: params.logger, + onIntegrityDrift: params.onIntegrityDrift, + }), logger: params.logger, - onIntegrityDrift: params.onIntegrityDrift, }), - logger: params.logger, - }); + ); } if ( @@ -481,19 +494,21 @@ export async function runPluginUpdateAttempt(params: { params.logger.warn?.( `Plugin "${params.pluginId}" has no beta ClawHub release for ${params.clawhubSpecs.fallbackLabel ?? params.effectiveSpec}; using ${params.clawhubSpecs.fallbackSpec} instead. Core update can still complete.`, ); - result = await installPluginFromClawHub({ - spec: params.clawhubSpecs.fallbackSpec, - config: params.config, - baseUrl: params.record.clawhubUrl, - mode: "update", - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - ...dryRunOption, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - expectedPluginId: params.pluginId, - ...params.clawHubRiskAcknowledgementOptions, - logger: params.logger, - }); + result = await installPluginFromClawHub( + installParams({ + spec: params.clawhubSpecs.fallbackSpec, + config: params.config, + baseUrl: params.record.clawhubUrl, + mode: "update", + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + ...dryRunOption, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + expectedPluginId: params.pluginId, + ...params.clawHubRiskAcknowledgementOptions, + logger: params.logger, + }), + ); activeClawHubInstallSpec = params.clawhubSpecs.fallbackSpec; if (params.officialNpmFallbackSpecs?.fallbackSpec) { officialNpmFallbackInstallSpec = params.officialNpmFallbackSpecs.fallbackSpec; @@ -519,19 +534,21 @@ export async function runPluginUpdateAttempt(params: { channelFallbackSuffix = params.dryRun ? ` (warning: official ClawHub artifact fallback would use ${officialNpmFallbackInstallSpec}).` : ` (warning: official ClawHub artifact fallback used ${officialNpmFallbackInstallSpec}).`; - result = await installNpmSpec({ - spec: officialNpmFallbackInstallSpec, - config: params.config, - mode: "update", - extensionsDir: params.extensionsDir, - timeoutMs: params.timeoutMs, - ...dryRunOption, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - trustedSourceLinkedOfficialInstall: true, - expectedPluginId: params.pluginId, - expectedReplacementPluginId: params.expectedReplacementPluginId, - logger: params.logger, - }); + result = await installNpmSpec( + installParams({ + spec: officialNpmFallbackInstallSpec, + config: params.config, + mode: "update", + extensionsDir: params.extensionsDir, + timeoutMs: params.timeoutMs, + ...dryRunOption, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + trustedSourceLinkedOfficialInstall: true, + expectedPluginId: params.pluginId, + expectedReplacementPluginId: params.expectedReplacementPluginId, + logger: params.logger, + }), + ); } return { diff --git a/src/plugins/update-installed.ts b/src/plugins/update-installed.ts index 2d56039f200d..5f06e390ea7e 100644 --- a/src/plugins/update-installed.ts +++ b/src/plugins/update-installed.ts @@ -11,6 +11,7 @@ import { resolveBundledPluginSources } from "./bundled-sources.js"; import { buildClawHubPluginInstallRecordFields } from "./clawhub-install-records.js"; import type { ClawHubRiskAcknowledgementRequest } from "./clawhub.js"; import { normalizePluginsConfig, resolveEffectiveEnableState } from "./config-state.js"; +import { copyPluginInstallTransactionRequest } from "./install-transaction.js"; import { PLUGIN_INSTALL_ERROR_CODE, resolvePluginInstallDir } from "./install.js"; import { buildNpmResolutionInstallFields, @@ -47,10 +48,8 @@ import { runPluginUpdateWithClawHubLease, } from "./update-claw-lifecycle.js"; import { - disablePluginAfterUpdateFailure, hasRunnableInstalledNpmPayload, migratePluginConfigId, - repairOpenClawPeerLinksForNpmInstalls, repairRegisteredOpenClawHostLink, resolveRecordedExtensionsDir, withoutPluginInstallRecord, @@ -77,6 +76,12 @@ import { type PluginUpdateOutcome, type PluginUpdateSummary, } from "./update-source.js"; +import { + createPluginUpdateTransactionState, + finalizePluginUpdateSummary, + recordPluginUpdateFailure, + recordPluginUpdateTransaction, +} from "./update-summary.js"; export async function updateNpmInstalledPlugins(params: { config: OpenClawConfig; @@ -105,6 +110,7 @@ export async function updateNpmInstalledPlugins(params: { : undefined; const bundled = resolveBundledPluginSources({}); const outcomes: PluginUpdateOutcome[] = []; + const transactionState = createPluginUpdateTransactionState(params); let next = params.config; let changed = false; let ranNpmInstaller = false; @@ -125,32 +131,18 @@ export async function updateNpmInstalledPlugins(params: { installedPayloadRunnable?: boolean; } = {}, ) => { - // Metadata failure is advisory only when a runnable payload is still installed. - // Missing-payload repair must keep disabling the broken config entry. - const preserveInstalledPayload = - options.code === PLUGIN_INSTALL_ERROR_CODE.NPM_METADATA_FAILURE && - options.installedPayloadRunnable === true; - if (params.disableOnFailure && !params.dryRun && !preserveInstalledPayload) { - const disabledMessage = - `Disabled "${pluginId}" after plugin update failure; OpenClaw will continue without it. ` + - message; - logger.warn?.(disabledMessage); - next = disablePluginAfterUpdateFailure(next, pluginId); - changed = true; - outcomes.push({ - pluginId, - status: "skipped", - message: disabledMessage, - ...(options.channelFallback ? { channelFallback: options.channelFallback } : {}), - }); - return; - } - outcomes.push({ + const failure = recordPluginUpdateFailure({ + config: next, + disableOnFailure: params.disableOnFailure, + dryRun: params.dryRun, + logger, + outcomes, pluginId, - status: "error", message, - ...(options.channelFallback ? { channelFallback: options.channelFallback } : {}), + options, }); + next = failure.config; + changed ||= failure.changed; }; for (const pluginId of targets) { @@ -505,27 +497,29 @@ export async function updateNpmInstalledPlugins(params: { } const runAttempt = () => - runPluginUpdateAttempt({ - pluginId, - record, - config: params.config, - dryRun: params.dryRun === true, - effectiveSpec, - extensionsDir, - timeoutMs: params.timeoutMs, - dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, - expectedIntegrity, - npmSpecs, - clawhubSpecs, - officialNpmFallbackSpecs, - trustedSourceLinkedOfficialInstall, - expectedReplacementPluginId: replacementPluginId, - getFallbackExpectedIntegrity, - installNpmSpecForUpdate, - logger, - onIntegrityDrift: params.onIntegrityDrift, - clawHubRiskAcknowledgementOptions, - }); + runPluginUpdateAttempt( + copyPluginInstallTransactionRequest(params, { + pluginId, + record, + config: params.config, + dryRun: params.dryRun === true, + effectiveSpec, + extensionsDir, + timeoutMs: params.timeoutMs, + dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall, + expectedIntegrity, + npmSpecs, + clawhubSpecs, + officialNpmFallbackSpecs, + trustedSourceLinkedOfficialInstall, + expectedReplacementPluginId: replacementPluginId, + getFallbackExpectedIntegrity, + installNpmSpecForUpdate, + logger, + onIntegrityDrift: params.onIntegrityDrift, + clawHubRiskAcknowledgementOptions, + }), + ); const attempt = await runPluginUpdateWithClawHubLease({ pluginId, clawhubPackage: recordClawHubPackage, @@ -638,6 +632,7 @@ export async function updateNpmInstalledPlugins(params: { } const resolvedPluginId = result.pluginId; + recordPluginUpdateTransaction(transactionState, result, pluginId, resolvedPluginId); if (resolvedPluginId !== pluginId) { next = migratePluginConfigId(next, pluginId, resolvedPluginId); } @@ -711,10 +706,12 @@ export async function updateNpmInstalledPlugins(params: { ); } - if (ranNpmInstaller) { - const repairedPeerLinks = await repairOpenClawPeerLinksForNpmInstalls({ config: next, logger }); - changed = repairedPeerLinks || changed; - } - - return { config: next, changed, outcomes }; + return await finalizePluginUpdateSummary({ + config: next, + changed, + outcomes, + ranNpmInstaller, + logger, + transactionState, + }); } diff --git a/src/plugins/update-summary.ts b/src/plugins/update-summary.ts new file mode 100644 index 000000000000..ecb876b1a955 --- /dev/null +++ b/src/plugins/update-summary.ts @@ -0,0 +1,113 @@ +import type { OpenClawConfig } from "../config/types.openclaw.js"; +import { + attachPluginInstallOwnerMigrations, + resolvePluginInstallTransaction, + resolvePluginInstallTransactionSink, + settlePluginInstallTransactions, + type PluginInstallTransaction, +} from "./install-transaction.js"; +import { PLUGIN_INSTALL_ERROR_CODE } from "./install.js"; +import { + disablePluginAfterUpdateFailure, + repairOpenClawPeerLinksForNpmInstalls, +} from "./update-config.js"; +import type { + PluginUpdateChannelFallback, + PluginUpdateLogger, + PluginUpdateOutcome, + PluginUpdateSummary, +} from "./update-source.js"; + +export function recordPluginUpdateFailure(params: { + config: OpenClawConfig; + disableOnFailure?: boolean; + dryRun?: boolean; + logger: PluginUpdateLogger; + outcomes: PluginUpdateOutcome[]; + pluginId: string; + message: string; + options?: { + channelFallback?: PluginUpdateChannelFallback; + code?: string; + installedPayloadRunnable?: boolean; + }; +}): { config: OpenClawConfig; changed: boolean } { + const options = params.options ?? {}; + const preserveInstalledPayload = + options.code === PLUGIN_INSTALL_ERROR_CODE.NPM_METADATA_FAILURE && + options.installedPayloadRunnable === true; + if (params.disableOnFailure && !params.dryRun && !preserveInstalledPayload) { + const message = + `Disabled "${params.pluginId}" after plugin update failure; OpenClaw will continue without it. ` + + params.message; + params.logger.warn?.(message); + params.outcomes.push({ + pluginId: params.pluginId, + status: "skipped", + message, + ...(options.channelFallback ? { channelFallback: options.channelFallback } : {}), + }); + return { + config: disablePluginAfterUpdateFailure(params.config, params.pluginId), + changed: true, + }; + } + params.outcomes.push({ + pluginId: params.pluginId, + status: "error", + message: params.message, + ...(options.channelFallback ? { channelFallback: options.channelFallback } : {}), + }); + return { config: params.config, changed: false }; +} + +export function createPluginUpdateTransactionState(params: object) { + return { + transactions: [] as PluginInstallTransaction[], + installOwnerMigrations: {} as Record, + transactionSink: resolvePluginInstallTransactionSink(params), + }; +} + +export function recordPluginUpdateTransaction( + state: ReturnType, + result: object, + pluginId: string, + resolvedPluginId: string, +): void { + const transaction = resolvePluginInstallTransaction(result); + if (transaction) { + state.transactions.push(transaction); + state.transactionSink?.push(transaction); + } + if (resolvedPluginId !== pluginId) { + state.installOwnerMigrations[pluginId] = resolvedPluginId; + } +} + +export async function finalizePluginUpdateSummary(params: { + config: OpenClawConfig; + changed: boolean; + outcomes: PluginUpdateOutcome[]; + ranNpmInstaller: boolean; + logger: PluginUpdateLogger; + transactionState: ReturnType; +}): Promise { + let changed = params.changed; + if (params.ranNpmInstaller) { + try { + changed = + (await repairOpenClawPeerLinksForNpmInstalls({ + config: params.config, + logger: params.logger, + })) || changed; + } catch (error) { + await settlePluginInstallTransactions(params.transactionState.transactions, "rollback"); + throw error; + } + } + const summary = { config: params.config, changed, outcomes: params.outcomes }; + return Object.keys(params.transactionState.installOwnerMigrations).length > 0 + ? attachPluginInstallOwnerMigrations(summary, params.transactionState.installOwnerMigrations) + : summary; +} diff --git a/test/e2e/qa-lab/plugins/plugin-lifecycle-probe-runtime.ts b/test/e2e/qa-lab/plugins/plugin-lifecycle-probe-runtime.ts index db2be97f7455..b25e98ca0aae 100644 --- a/test/e2e/qa-lab/plugins/plugin-lifecycle-probe-runtime.ts +++ b/test/e2e/qa-lab/plugins/plugin-lifecycle-probe-runtime.ts @@ -88,6 +88,10 @@ function requiredConfig(env: ProbeEnv = process.env) { return readRequiredJson(configPath(env)); } +function writeConfig(config: Record, env: ProbeEnv = process.env) { + fs.writeFileSync(configPath(env), `${JSON.stringify(config, null, 2)}\n`, "utf8"); +} + function assertProbe(condition: unknown, message: string): asserts condition { if (!condition) { throw new Error(message); @@ -216,6 +220,38 @@ export function assertUninstalled(pluginId: string, env: ProbeEnv = process.env) ); } +function assertRemovedChildPolicy(pluginId: string, env: ProbeEnv = process.env) { + const cfg = requiredConfig(env) as { + plugins?: { + allow?: string[]; + deny?: string[]; + entries?: Record; + load?: { paths?: unknown[] }; + slots?: { memory?: string; contextEngine?: string }; + }; + }; + assertProbe(!cfg.plugins?.entries?.[pluginId], `plugin entry survived for ${pluginId}`); + assertProbe( + !(cfg.plugins?.allow ?? []).includes(pluginId), + `allow policy survived for ${pluginId}`, + ); + assertProbe( + !(cfg.plugins?.deny ?? []).includes(pluginId), + `deny policy survived for ${pluginId}`, + ); + assertProbe( + !(cfg.plugins?.load?.paths ?? []).some((entry) => + String(entry).endsWith(`/${pluginId.split("/").at(-1)}.js`), + ), + `load path survived for ${pluginId}`, + ); + assertProbe(cfg.plugins?.slots?.memory !== pluginId, `memory slot survived for ${pluginId}`); + assertProbe( + cfg.plugins?.slots?.contextEngine !== pluginId, + `context engine slot survived for ${pluginId}`, + ); +} + export function parseDurationMs(value: string | undefined, fallback: string) { const text = (value || fallback).trim(); if (text === "0") { @@ -439,6 +475,26 @@ async function packFixturePlugin( await runCommand("tar", ["-czf", outputTgz, "-C", packDir, "package"]); } +async function packFixturePluginPack( + packDir: string, + outputTgz: string, + pluginId: string, + version: string, + entries: readonly string[], +) { + const packageDir = path.join(packDir, "package"); + fs.mkdirSync(packageDir, { recursive: true }); + await runCommand("node", [ + "scripts/e2e/lib/fixture.mjs", + "plugin-pack", + packageDir, + pluginId, + version, + entries.join(","), + ]); + await runCommand("tar", ["-czf", outputTgz, "-C", packDir, "package"]); +} + async function startNpmFixtureRegistry( registryRoot: string, packages: readonly [packageName: string, version: string, tarball: string][], @@ -446,6 +502,7 @@ async function startNpmFixtureRegistry( ): Promise { const serverLog = path.join(registryRoot, "npm-registry.log"); const serverPortFile = path.join(registryRoot, "npm-registry-port"); + fs.rmSync(serverPortFile, { force: true }); const logFd = fs.openSync(serverLog, "a"); const child = spawn( "node", @@ -535,16 +592,28 @@ async function runRuntimeInspect(params: { async function runPluginLifecycleMatrix() { const pluginId = "lifecycle-claw"; const packageName = "@openclaw/lifecycle-claw"; + const packOwner = "lifecycle-pack"; + const packPackageName = "@openclaw/lifecycle-pack"; + const packOne = `${packOwner}/one`; + const packTwo = `${packOwner}/two`; + const packOld = `${packOwner}/old`; + const packRenamed = `${packOwner}/renamed`; const resourceDir = tempDirs.make("openclaw-plugin-lifecycle-matrix-"); const npmPrefix = "/tmp/npm-prefix"; const env = createMatrixStateEnv(resourceDir); const tarballV1 = path.join(resourceDir, "lifecycle-claw-1.0.0.tgz"); const tarballV2 = path.join(resourceDir, "lifecycle-claw-2.0.0.tgz"); + const packTarballV1 = path.join(resourceDir, "lifecycle-pack-1.0.0.tgz"); + const packTarballV2 = path.join(resourceDir, "lifecycle-pack-2.0.0.tgz"); const inspectV1 = path.join(resourceDir, "plugin-lifecycle-inspect-v1.json"); const inspectDisabled = path.join(resourceDir, "plugin-lifecycle-inspect-disabled.json"); const inspectReenabled = path.join(resourceDir, "plugin-lifecycle-inspect-reenabled.json"); const inspectV2 = path.join(resourceDir, "plugin-lifecycle-inspect-v2.json"); const inspectDowngradeV1 = path.join(resourceDir, "plugin-lifecycle-inspect-downgrade-v1.json"); + const inspectPackOneV1 = path.join(resourceDir, "plugin-pack-one-v1.json"); + const inspectPackTwoDisabled = path.join(resourceDir, "plugin-pack-two-disabled.json"); + const inspectPackOneV2 = path.join(resourceDir, "plugin-pack-one-v2.json"); + const inspectPackRenamedV2 = path.join(resourceDir, "plugin-pack-renamed-v2.json"); const summaryTsv = path.join(resourceDir, "resource-summary.tsv"); let registry: RegistryServer | undefined; @@ -575,6 +644,15 @@ async function runPluginLifecycleMatrix() { "lifecycle.v1", "Lifecycle Claw", ); + await packFixturePluginPack(path.join(packRoot, "pack-v1"), packTarballV1, packOwner, "1.0.0", [ + "one", + "two", + "old", + ]); + await packFixturePluginPack(path.join(packRoot, "pack-v2"), packTarballV2, packOwner, "2.0.0", [ + "one", + "renamed", + ]); await packFixturePlugin( path.join(packRoot, "v2"), tarballV2, @@ -588,10 +666,11 @@ async function runPluginLifecycleMatrix() { [ [packageName, "1.0.0", tarballV1], [packageName, "2.0.0", tarballV2], + [packPackageName, "1.0.0", packTarballV1], ], matrixEnv, ); - const runEnv = registry.env as MatrixEnv; + let runEnv = registry.env as MatrixEnv; await runMeasured( summaryTsv, @@ -688,14 +767,144 @@ async function runPluginLifecycleMatrix() { `failed to remove plugin code before missing-code uninstall: ${installedPath}`, ); + let missingCodeUninstallFailed = false; + try { + await runMeasured( + summaryTsv, + "missing-code-uninstall", + "node", + [entry, "plugins", "uninstall", pluginId, "--force"], + runEnv, + ); + } catch { + missingCodeUninstallFailed = true; + } + assertProbe( + missingCodeUninstallFailed, + "missing-code uninstall must fail closed without authoritative child metadata", + ); + assertProbe(recordFor(pluginId, runEnv), "missing-code uninstall removed the install record"); + assertEnabled(pluginId, true, runEnv); + await runMeasured( summaryTsv, - "missing-code-uninstall", + "pack-install-v1", "node", - [entry, "plugins", "uninstall", pluginId, "--force"], + [entry, "plugins", "install", `npm:${packPackageName}@latest`, "--force"], runEnv, ); - assertUninstalled(pluginId, runEnv); + assertVersion(packOwner, "1.0.0", runEnv); + assertEnabled(packOne, true, runEnv); + assertEnabled(packTwo, true, runEnv); + assertEnabled(packOld, true, runEnv); + await runRuntimeInspect({ + summaryTsv, + phase: "pack-inspect-one-v1", + entry, + pluginId: packOne, + inspectPath: inspectPackOneV1, + env: runEnv, + }); + assertInspectLoaded(packOne, inspectPackOneV1); + + await runMeasured( + summaryTsv, + "pack-disable-two", + "node", + [entry, "plugins", "disable", packTwo], + runEnv, + ); + assertEnabled(packTwo, false, runEnv); + await runRuntimeInspect({ + summaryTsv, + phase: "pack-inspect-two-disabled", + entry, + pluginId: packTwo, + inspectPath: inspectPackTwoDisabled, + env: runEnv, + }); + assertInspectDisabled(packTwo, inspectPackTwoDisabled); + + const policyConfig = requiredConfig(runEnv) as { + plugins?: Record & { + allow?: string[]; + deny?: string[]; + entries?: Record; + load?: { paths?: string[] }; + slots?: Record; + }; + }; + policyConfig.plugins = { + ...policyConfig.plugins, + allow: [packOne, packTwo, packOld], + deny: [packOld], + entries: { + ...policyConfig.plugins?.entries, + [packOld]: { enabled: true }, + }, + }; + writeConfig(policyConfig, runEnv); + + registry.stop(); + registry = await startNpmFixtureRegistry( + registryRoot, + [ + [packageName, "1.0.0", tarballV1], + [packageName, "2.0.0", tarballV2], + [packPackageName, "1.0.0", packTarballV1], + [packPackageName, "2.0.0", packTarballV2], + ], + matrixEnv, + ); + runEnv = registry.env as MatrixEnv; + + await runMeasured( + summaryTsv, + "pack-child-update-v2", + "node", + [entry, "plugins", "update", packTwo], + runEnv, + ); + assertVersion(packOwner, "2.0.0", runEnv); + assertEnabled(packOne, true, runEnv); + assertRemovedChildPolicy(packTwo, runEnv); + assertRemovedChildPolicy(packOld, runEnv); + await runRuntimeInspect({ + summaryTsv, + phase: "pack-inspect-one-v2", + entry, + pluginId: packOne, + inspectPath: inspectPackOneV2, + env: runEnv, + }); + assertInspectLoaded(packOne, inspectPackOneV2); + await runRuntimeInspect({ + summaryTsv, + phase: "pack-inspect-renamed-v2", + entry, + pluginId: packRenamed, + inspectPath: inspectPackRenamedV2, + env: runEnv, + }); + assertInspectDisabled(packRenamed, inspectPackRenamedV2); + + const packInstallPath = installPath(packOwner, runEnv); + await runMeasured( + summaryTsv, + "pack-child-uninstall", + "node", + [entry, "plugins", "uninstall", packOne, "--force"], + runEnv, + ); + assertUninstalled(packOwner, runEnv); + assertUninstalled(packOne, runEnv); + assertUninstalled(packTwo, runEnv); + assertUninstalled(packOld, runEnv); + assertUninstalled(packRenamed, runEnv); + assertProbe( + !fs.existsSync(packInstallPath), + `pack install directory still exists after child-addressed uninstall: ${packInstallPath}`, + ); process.stdout.write( `Plugin lifecycle resource summary:\n${fs.readFileSync(summaryTsv, "utf8")}`, diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts index 0045edb14d75..36703db25c4b 100644 --- a/ui/src/i18n/locales/en.ts +++ b/ui/src/i18n/locales/en.ts @@ -2775,7 +2775,7 @@ export const en: TranslationMap = { remove: "Remove", removing: "Removing…", removeNamed: "Remove {name}", - removeConfirm: "Remove this plugin?", + removeConfirm: "Remove this plugin package and all of its entries?", cancel: "Cancel", removedRestart: "Removed {name}. A Gateway restart is required to apply the change.", verifiedSource: "Verified source", diff --git a/ui/src/pages/plugins/view.test.ts b/ui/src/pages/plugins/view.test.ts index 2bc2667b86f7..13c1a3d6fce0 100644 --- a/ui/src/pages/plugins/view.test.ts +++ b/ui/src/pages/plugins/view.test.ts @@ -325,7 +325,7 @@ describe("renderPlugins", () => { ); const confirm = container.querySelector(".plugins-remove-confirm"); - expect(normalizedText(confirm)).toContain("Remove this plugin?"); + expect(normalizedText(confirm)).toContain("Remove this plugin package and all of its entries?"); confirm?.querySelector(".btn.danger")?.click(); expect(onUninstall).toHaveBeenCalledWith("community-thing", rowKey); confirm?.querySelectorAll("button")[1]?.click(); From b8a0fa2e7a947e9f38e9141e22559170532358ba Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 12 Aug 2026 16:03:34 +0800 Subject: [PATCH 064/165] fix(plugins): derive media aliases from exports (#122523) --- .../plugin-sdk-native-resolver.test.ts | 39 ++++++++++++- src/plugins/plugin-sdk-native-resolver.ts | 18 +----- src/plugins/sdk-alias.test.ts | 56 ++++++++++++++++++- src/plugins/sdk-alias.ts | 26 +-------- 4 files changed, 94 insertions(+), 45 deletions(-) diff --git a/src/plugins/plugin-sdk-native-resolver.test.ts b/src/plugins/plugin-sdk-native-resolver.test.ts index afb6f39f5de1..135226b92ed7 100644 --- a/src/plugins/plugin-sdk-native-resolver.test.ts +++ b/src/plugins/plugin-sdk-native-resolver.test.ts @@ -93,6 +93,23 @@ function writeInternalCorePackageSource( return sourcePath; } +function writeInternalCorePackageExports( + root: string, + packageDir: string, + subpaths: readonly string[], +): void { + writeJsonFile(path.join(root, "packages", packageDir, "package.json"), { + name: `@openclaw/${packageDir}`, + exports: Object.fromEntries( + subpaths.map((subpath) => { + const exportKey = subpath ? `./${subpath}` : "."; + const distFile = `./dist/${subpath || "index"}.mjs`; + return [exportKey, { import: distFile, default: distFile }]; + }), + ), + }); +} + function addFakePluginSdkDistExport(root: string, subpath: string): string { const packageJsonPath = path.join(root, "package.json"); const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as { @@ -521,7 +538,19 @@ describe("installOpenClawPluginSdkNativeResolver", () => { ); const resultSource = writeInternalCorePackageSource(root, "normalization-core", "result.ts"); const agentIdSource = writeInternalCorePackageSource(root, "normalization-core", "agent-id.ts"); - const mediaCoreSource = writeInternalCorePackageSource(root, "media-core", "mime.ts"); + writeInternalCorePackageExports(root, "normalization-core", [ + "agent-id", + "boolean-coercion", + "result", + "string-coerce", + ]); + writeInternalCorePackageExports(root, "media-core", ["attachment-classify", "mime"]); + const mediaMimeSource = writeInternalCorePackageSource(root, "media-core", "mime.ts"); + const mediaAttachmentClassifySource = writeInternalCorePackageSource( + root, + "media-core", + "attachment-classify.ts", + ); const markdownCoreSource = writeInternalCorePackageSource( root, "markdown-core", @@ -543,6 +572,7 @@ describe("installOpenClawPluginSdkNativeResolver", () => { "acp-core", path.join("runtime", "types.ts"), ); + writeInternalCorePackageExports(root, "acp-core", ["runtime/types"]); const llmCoreSource = writeInternalCorePackageSource(root, "llm-core", "index.ts"); const externalPluginEntry = writeExternalPluginEntry(path.join(root, "external-plugin")); const coreSourceParent = path.join(root, "src", "config", "plugin-web-search-config.ts"); @@ -560,6 +590,7 @@ describe("installOpenClawPluginSdkNativeResolver", () => { expect(installedAliases).toContain("@openclaw/normalization-core/result"); expect(installedAliases).toContain("@openclaw/normalization-core/agent-id"); expect(installedAliases).toContain("@openclaw/media-core/mime"); + expect(installedAliases).toContain("@openclaw/media-core/attachment-classify"); expect(installedAliases).toContain("@openclaw/markdown-core/code-spans"); expect(installedAliases).toContain("@openclaw/ai/transports"); expect(installedAliases).toContain("@openclaw/ai/internal/retry-after"); @@ -583,8 +614,11 @@ describe("installOpenClawPluginSdkNativeResolver", () => { fs.realpathSync(requireFromCoreSource.resolve("@openclaw/normalization-core/agent-id")), ).toBe(fs.realpathSync(agentIdSource)); expect(fs.realpathSync(requireFromCoreSource.resolve("@openclaw/media-core/mime"))).toBe( - fs.realpathSync(mediaCoreSource), + fs.realpathSync(mediaMimeSource), ); + expect( + fs.realpathSync(requireFromCoreSource.resolve("@openclaw/media-core/attachment-classify")), + ).toBe(fs.realpathSync(mediaAttachmentClassifySource)); expect( fs.realpathSync(requireFromCoreSource.resolve("@openclaw/markdown-core/code-spans")), ).toBe(fs.realpathSync(markdownCoreSource)); @@ -609,6 +643,7 @@ describe("installOpenClawPluginSdkNativeResolver", () => { ).toThrow(); expect(() => requireFromPlugin.resolve("@openclaw/normalization-core/result")).toThrow(); expect(() => requireFromPlugin.resolve("@openclaw/media-core/mime")).toThrow(); + expect(() => requireFromPlugin.resolve("@openclaw/media-core/attachment-classify")).toThrow(); expect(() => requireFromPlugin.resolve("@openclaw/markdown-core/code-spans")).toThrow(); expect(() => requireFromPlugin.resolve("@openclaw/ai/transports")).toThrow(); expect(() => requireFromPlugin.resolve("@openclaw/ai/internal/retry-after")).toThrow(); diff --git a/src/plugins/plugin-sdk-native-resolver.ts b/src/plugins/plugin-sdk-native-resolver.ts index 85c1e83588db..ff1792273611 100644 --- a/src/plugins/plugin-sdk-native-resolver.ts +++ b/src/plugins/plugin-sdk-native-resolver.ts @@ -91,22 +91,6 @@ const INTERNAL_CORE_PACKAGE_ALIASES = [ ["internal/shared", path.join("internal", "shared.ts")], ], }, - { - packageName: "@openclaw/media-core", - packageDir: "media-core", - subpaths: [ - ["", "index.ts"], - ["base64", "base64.ts"], - ["constants", "constants.ts"], - ["content-length", "content-length.ts"], - ["file-name", "file-name.ts"], - ["inbound-path-policy", "inbound-path-policy.ts"], - ["inline-image-data-url", "inline-image-data-url.ts"], - ["media-source-url", "media-source-url.ts"], - ["mime", "mime.ts"], - ["read-byte-stream-with-limit", "read-byte-stream-with-limit.ts"], - ], - }, { packageName: "@openclaw/llm-core", packageDir: "llm-core", @@ -341,7 +325,7 @@ function listInternalCorePackageNativeAliases( }> = []; const internalCorePackageAliases = [ ...INTERNAL_CORE_PACKAGE_ALIASES, - ...["normalization-core", "acp-core"].map((packageDir) => ({ + ...["media-core", "normalization-core", "acp-core"].map((packageDir) => ({ packageName: `@openclaw/${packageDir}`, packageDir, subpaths: listWorkspacePackageExportAliasEntries({ diff --git a/src/plugins/sdk-alias.test.ts b/src/plugins/sdk-alias.test.ts index 5aee9dc45c5d..83c90946cda6 100644 --- a/src/plugins/sdk-alias.test.ts +++ b/src/plugins/sdk-alias.test.ts @@ -154,6 +154,32 @@ function writeWorkspacePackageEntry(params: { return { srcFile, distFile }; } +function writeWorkspacePackageExports( + root: string, + packageDir: string, + subpaths: readonly string[], +) { + mkdirSafeDir(path.join(root, "packages", packageDir)); + fs.writeFileSync( + path.join(root, "packages", packageDir, "package.json"), + JSON.stringify( + { + name: `@openclaw/${packageDir}`, + exports: Object.fromEntries( + subpaths.map((subpath) => { + const exportKey = subpath ? `./${subpath}` : "."; + const distFile = `./dist/${subpath || "index"}.mjs`; + return [exportKey, { import: distFile, default: distFile }]; + }), + ), + }, + null, + 2, + ), + "utf-8", + ); +} + type WorkspaceAliasFixture = readonly [ alias: `@openclaw/${string}`, packageDir: string, @@ -1148,6 +1174,15 @@ describe("plugin sdk alias helpers", () => { it("aliases workspace packages to source when dist artifacts are missing", () => { const fixture = createPluginSdkAliasFixture(); + writeWorkspacePackageExports(fixture.root, "media-core", ["", "attachment-classify", "mime"]); + writeWorkspacePackageExports(fixture.root, "acp-core", ["", "runtime/types"]); + writeWorkspacePackageExports(fixture.root, "normalization-core", [ + "", + "agent-id", + "boolean-coercion", + "result", + "string-coerce", + ]); const workspaceAliases = writeWorkspaceAliasFixtures(fixture.root, [ ["@openclaw/gateway-client", "gateway-client", "index"], ["@openclaw/gateway-client/timeouts", "gateway-client", "timeouts"], @@ -1160,6 +1195,7 @@ describe("plugin sdk alias helpers", () => { ["@openclaw/media-generation-core", "media-generation-core", "index"], ["@openclaw/media-generation-core/model-ref", "media-generation-core", "model-ref"], ["@openclaw/media-core", "media-core", "index"], + ["@openclaw/media-core/attachment-classify", "media-core", "attachment-classify"], ["@openclaw/media-core/mime", "media-core", "mime"], ["@openclaw/acp-core", "acp-core", "index"], ["@openclaw/acp-core/runtime/types", "acp-core", "runtime/types"], @@ -1193,6 +1229,9 @@ describe("plugin sdk alias helpers", () => { it("aliases workspace package subpaths to dist when available", () => { const fixture = createPluginSdkAliasFixture(); + writeWorkspacePackageExports(fixture.root, "media-core", ["attachment-classify"]); + writeWorkspacePackageExports(fixture.root, "acp-core", ["normalize-text"]); + writeWorkspacePackageExports(fixture.root, "normalization-core", ["record-coerce"]); const workspaceAliases = writeWorkspaceAliasFixtures(fixture.root, [ ["@openclaw/gateway-client/readiness", "gateway-client", "readiness"], [ @@ -1203,6 +1242,7 @@ describe("plugin sdk alias helpers", () => { ["@openclaw/gateway-protocol/frame-guards", "gateway-protocol", "frame-guards"], ["@openclaw/markdown-core/render", "markdown-core", "render"], ["@openclaw/media-generation-core/catalog", "media-generation-core", "catalog"], + ["@openclaw/media-core/attachment-classify", "media-core", "attachment-classify"], [ "@openclaw/acp-core/normalize-text", "acp-core", @@ -1254,9 +1294,18 @@ describe("plugin sdk alias helpers", () => { ); mkdirSafeDir(path.dirname(normalizationAgentId)); fs.writeFileSync(normalizationAgentId, "export {};\n", "utf-8"); - const cwdWithoutOpenClawPackage = makeTempDir(); + const mediaAttachmentClassify = path.join( + fixture.root, + "dist", + "media-core", + "attachment-classify.js", + ); + mkdirSafeDir(path.dirname(mediaAttachmentClassify)); + fs.writeFileSync(mediaAttachmentClassify, "export {};\n", "utf-8"); + const staleCheckout = createPluginSdkAliasFixture(); + writeWorkspacePackageExports(staleCheckout.root, "media-core", ["mime"]); - const aliases = withCwd(cwdWithoutOpenClawPackage, () => + const aliases = withCwd(staleCheckout.root, () => withEnv({ NODE_ENV: undefined }, () => buildPluginLoaderAliasMap(sourcePluginEntry, undefined, undefined, "dist"), ), @@ -1268,6 +1317,9 @@ describe("plugin sdk alias helpers", () => { expect(fs.realpathSync(aliases["@openclaw/normalization-core/agent-id"] ?? "")).toBe( fs.realpathSync(normalizationAgentId), ); + expect(fs.realpathSync(aliases["@openclaw/media-core/attachment-classify"] ?? "")).toBe( + fs.realpathSync(mediaAttachmentClassify), + ); }); it("aliases bundled plugin package public surfaces for source plugin transforms", () => { diff --git a/src/plugins/sdk-alias.ts b/src/plugins/sdk-alias.ts index 9df3b3f9ab7e..84b871140c0a 100644 --- a/src/plugins/sdk-alias.ts +++ b/src/plugins/sdk-alias.ts @@ -517,21 +517,6 @@ const WORKSPACE_PACKAGE_ALIAS_SUBPATHS = [ ], ], ["media-generation-core", ["", "capability-model-ref", "catalog", "model-ref", "normalization"]], - [ - "media-core", - [ - "", - "base64", - "constants", - "content-length", - "file-name", - "inbound-path-policy", - "inline-image-data-url", - "media-source-url", - "mime", - "read-byte-stream-with-limit", - ], - ], ["retry", [""]], [ "terminal-core", @@ -669,14 +654,7 @@ export function listWorkspacePackageExportAliasEntries(params: { params.packageDir, "package.json", ); - const fallbackPackageRoot = resolveOpenClawPackageRootSync({ cwd: process.cwd() }); - const packageJson = - tryReadJsonSync(packageJsonPath) ?? - (fallbackPackageRoot - ? tryReadJsonSync( - path.join(fallbackPackageRoot, "packages", params.packageDir, "package.json"), - ) - : null); + const packageJson = tryReadJsonSync(packageJsonPath); const exports = packageJson?.exports; if (!exports || typeof exports !== "object" || Array.isArray(exports)) { return listRootPackagedWorkspacePackageAliasEntries(params); @@ -914,7 +892,7 @@ function resolveWorkspacePackageAliasMap(params: { const aliasMap: Record = {}; const workspacePackageAliasEntries = [ ...WORKSPACE_PACKAGE_ALIAS_ENTRIES, - ...["normalization-core", "acp-core"].flatMap((packageDir) => + ...["media-core", "normalization-core", "acp-core"].flatMap((packageDir) => listWorkspacePackageExportAliasEntries({ packageRoot, packageName: `@openclaw/${packageDir}`, From 716f996be8db3082876180a377b69931dd0cdf68 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 12 Aug 2026 16:08:19 +0800 Subject: [PATCH 065/165] fix(ci): prepare sandbox before repo E2E (#122525) --- .../workflows/openclaw-live-and-e2e-checks-reusable.yml | 5 ++++- test/scripts/ci-workflow-guards.test.ts | 8 ++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/.github/workflows/openclaw-live-and-e2e-checks-reusable.yml b/.github/workflows/openclaw-live-and-e2e-checks-reusable.yml index 77f8ae27da4d..4a39fab1439a 100644 --- a/.github/workflows/openclaw-live-and-e2e-checks-reusable.yml +++ b/.github/workflows/openclaw-live-and-e2e-checks-reusable.yml @@ -977,7 +977,7 @@ jobs: if: inputs.include_repo_e2e && inputs.live_suite_filter == '' continue-on-error: ${{ inputs.advisory }} runs-on: ${{ inputs.use_github_hosted_runners && 'ubuntu-24.04' || 'blacksmith-32vcpu-ubuntu-2404' }} - timeout-minutes: ${{ inputs.release_test_profile == 'full' && 90 || 60 }} + timeout-minutes: 90 env: OPENCLAW_BUILD_PRIVATE_QA: "1" OPENCLAW_ENABLE_PRIVATE_QA_CLI: "1" @@ -1004,6 +1004,9 @@ jobs: - name: Install Playwright Chromium run: pnpm --dir ui exec playwright install --with-deps chromium + - name: Build sandbox image + run: scripts/sandbox-setup.sh + - name: Run repo E2E suite run: pnpm test:e2e diff --git a/test/scripts/ci-workflow-guards.test.ts b/test/scripts/ci-workflow-guards.test.ts index 4f8b8fa0695e..0fc41df842d6 100644 --- a/test/scripts/ci-workflow-guards.test.ts +++ b/test/scripts/ci-workflow-guards.test.ts @@ -3208,6 +3208,14 @@ NODE OPENCLAW_BUILD_PRIVATE_QA: "1", OPENCLAW_ENABLE_PRIVATE_QA_CLI: "1", }); + expect(releaseChecks.jobs.validate_repo_e2e["timeout-minutes"]).toBe(90); + const repoE2eSteps = releaseChecks.jobs.validate_repo_e2e.steps as WorkflowStep[]; + const sandboxSetupIndex = repoE2eSteps.findIndex( + (step) => step.name === "Build sandbox image" && step.run === "scripts/sandbox-setup.sh", + ); + const repoE2eIndex = repoE2eSteps.findIndex((step) => step.name === "Run repo E2E suite"); + expect(sandboxSetupIndex).toBeGreaterThanOrEqual(0); + expect(repoE2eIndex).toBeGreaterThan(sandboxSetupIndex); const targetedGroupStep = releaseChecks.jobs.plan_docker_lane_groups.steps.find( (step: WorkflowStep) => step.name === "Build targeted Docker lane groups", ); From 85a176b98ab114bf7dd58604ae64f004d73933c4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:08:33 -0700 Subject: [PATCH 066/165] feat(ui): commit-scoped session diff viewer with file, sync, and view menus (#122470) * feat(ui): commit-scoped session diff viewer with file, sync, and view menus The Control UI session diff panel becomes a dense Amp-style viewer: per-file menus (copy path, open file, reveal in file tree, open in editor), a Sync Locally popover with a copyable git fetch command, view options (collapse all, wrapping, split/unified layout), and a sticky footer that reports how far the branch is ahead of its merge base and switches between all changes, uncommitted work, and individual commits. sessions.diff gains an additive scope param (all | uncommitted | commit) plus commits, aheadCount, and mergeBase metadata. Commit-scope diffs read only the object database, skip untracked collection, and bypass session-start baseline filtering; unknown commits surface a typed unavailableReason. Offscreen file bodies use content-visibility so large diffs stay responsive. * fix(ui): satisfy session diff CI gates * fix(gateway): fence commit-scoped session diffs to the advertised branch history ClawSweeper found that commit-scoped sessions.diff accepted any commit resolvable in the checkout. Fence operator.read commit reads to the advertised merge-base..HEAD history and cover sibling-branch and base-history commits. --- .../OpenClawProtocol/GatewayModels.swift | 46 +- .../agent-harness-runtime.json | 2 +- .../agent-harness.json | 2 +- .../agent-runtime.json | 2 +- .../plugin-sdk-api-baseline/channel-core.json | 2 +- .../channel-entry-contract.json | 2 +- .../channel-inbound.json | 2 +- .../channel-message.json | 2 +- .../channel-outbound.json | 2 +- .../channel-plugin-common.json | 2 +- .../plugin-sdk-api-baseline/core.json | 2 +- .../plugin-sdk-api-baseline/discord.json | 2 +- .../gateway-runtime.json | 2 +- .../inbound-reply-dispatch.json | 2 +- .../meeting-runtime.json | 2 +- .../plugin-sdk-api-baseline/plugin-entry.json | 2 +- .../plugin-runtime.json | 2 +- .../provider-catalog-runtime.json | 2 +- .../plugin-sdk-api-baseline/tool-plugin.json | 2 +- .../webhook-ingress.json | 2 +- docs/web/control-ui.md | 2 +- packages/gateway-protocol/src/index.ts | 2 + ...ocol-schema-fragment-sessions-lifecycle.ts | 2 + .../gateway-protocol/src/schema/sessions.ts | 29 +- .../server-methods/sessions-diff.test.ts | 121 +++++- src/gateway/server-methods/sessions-diff.ts | 31 +- src/sessions/session-diff-revisions.ts | 108 +++++ src/sessions/session-diff.ts | 175 ++++---- ui/src/e2e/chat-session-diff.e2e.test.ts | 164 +++++-- ui/src/i18n/locales/en.ts | 27 ++ ui/src/lib/chat/session-diff-split.test.ts | 22 + ui/src/lib/chat/session-diff-split.ts | 44 ++ .../pages/chat/components/chat-diff-render.ts | 15 +- .../chat/components/chat-session-workspace.ts | 5 +- ui/src/pages/chat/components/chat-sidebar.ts | 12 +- .../chat/components/session-diff-menus.ts | 332 ++++++++++++++ .../components/session-diff-panel.test.ts | 1 + .../chat/components/session-diff-panel.ts | 372 ++++++++++++++-- .../chat/components/session-diff-render.ts | 44 ++ ui/src/styles/chat/sidebar.css | 404 +++++++++++++++++- 40 files changed, 1774 insertions(+), 222 deletions(-) create mode 100644 src/sessions/session-diff-revisions.ts create mode 100644 ui/src/lib/chat/session-diff-split.test.ts create mode 100644 ui/src/lib/chat/session-diff-split.ts create mode 100644 ui/src/pages/chat/components/session-diff-menus.ts create mode 100644 ui/src/pages/chat/components/session-diff-render.ts diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift index 4054619e80ad..ef5b91843760 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift @@ -182,6 +182,12 @@ public enum SessionDiffFileStatus: String, Codable, Sendable { case renamed = "renamed" } +public enum SessionDiffScope: String, Codable, Sendable { + case all = "all" + case uncommitted = "uncommitted" + case commit = "commit" +} + public enum TaskSuggestionResolution: String, Codable, Sendable { case dismissed = "dismissed" case accepted = "accepted" @@ -8005,21 +8011,47 @@ public struct SessionDiffFile: Codable, Sendable { } } +public struct SessionDiffCommit: Codable, Sendable { + public let sha: String + public let subject: String + + public init( + sha: String, + subject: String) + { + self.sha = sha + self.subject = subject + } + + private enum CodingKeys: String, CodingKey { + case sha + case subject + } +} + public struct SessionsDiffParams: Codable, Sendable { public let sessionkey: String public let agentid: String? + public let scope: SessionDiffScope? + public let commit: String? public init( sessionkey: String, - agentid: String? = nil) + agentid: String? = nil, + scope: SessionDiffScope? = nil, + commit: String? = nil) { self.sessionkey = sessionkey self.agentid = agentid + self.scope = scope + self.commit = commit } private enum CodingKeys: String, CodingKey { case sessionkey = "sessionKey" case agentid = "agentId" + case scope + case commit } } @@ -8028,6 +8060,9 @@ public struct SessionsDiffResult: Codable, Sendable { public let root: String? public let branch: String? public let baseref: String? + public let aheadcount: Int? + public let commits: [SessionDiffCommit]? + public let mergebase: SessionDiffCommit? public let files: [SessionDiffFile] public let additions: Int public let deletions: Int @@ -8039,6 +8074,9 @@ public struct SessionsDiffResult: Codable, Sendable { root: String? = nil, branch: String? = nil, baseref: String? = nil, + aheadcount: Int? = nil, + commits: [SessionDiffCommit]? = nil, + mergebase: SessionDiffCommit? = nil, files: [SessionDiffFile], additions: Int, deletions: Int, @@ -8049,6 +8087,9 @@ public struct SessionsDiffResult: Codable, Sendable { self.root = root self.branch = branch self.baseref = baseref + self.aheadcount = aheadcount + self.commits = commits + self.mergebase = mergebase self.files = files self.additions = additions self.deletions = deletions @@ -8061,6 +8102,9 @@ public struct SessionsDiffResult: Codable, Sendable { case root case branch case baseref = "baseRef" + case aheadcount = "aheadCount" + case commits + case mergebase = "mergeBase" case files case additions case deletions diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json index 71e7a14df4c3..b14cb45a6a19 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json @@ -1 +1 @@ -{"contentHash":"8c6ff70bbf195705355c6599c50819065f5f350f0faaddc4a868b5e86da65e28","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} +{"contentHash":"40f4454b9a60030b2a1ba050abaad8993e821cb84444365728dc3d12de86e1af","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json index 24728a1bca39..6c5a518d1f2b 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json @@ -1 +1 @@ -{"contentHash":"91311c46d7fa124d5b79e0a8a6640f2ef8436c5000c1dafa3391f8c1303054b7","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} +{"contentHash":"c700bd1f9821574a3d0a20815d55fc8b3857d71cdbfeab0a9bfb394bb81fe745","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json index ce3ba2b55349..7d26079d9ecf 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-runtime.json @@ -1 +1 @@ -{"contentHash":"fac71b2c80db2874419a589646fd560e8a8ad43dba93f5a6d26a73c171a0b4ba","entrypoint":"agent-runtime","importSpecifier":"openclaw/plugin-sdk/agent-runtime"} +{"contentHash":"4b54a0f38cb2d46ac2446e6ec7003fddbe1cbe19d8b34d28354b91cb70293f02","entrypoint":"agent-runtime","importSpecifier":"openclaw/plugin-sdk/agent-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-core.json b/docs/.generated/plugin-sdk-api-baseline/channel-core.json index a546efe66f2f..886771e7b69f 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-core.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-core.json @@ -1 +1 @@ -{"contentHash":"c3b22d889dc4c65a0ab8c4f5743e49df7f18a399a77b271a56e2cd60a2671fea","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} +{"contentHash":"30538b51154ba0bdebf6bf02eefd16c73b7fd1043b074f3595db3a3088bfc98c","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json index 4bddaffac84c..291a40c23610 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json @@ -1 +1 @@ -{"contentHash":"7cc678c87c2d6063305951bc9bcd75f78f4fe2a9408a263bc1cb294c66075b50","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} +{"contentHash":"0c9c99f96d0c050db645580b2bb91405485423e2d7fd14031b101d4b44026537","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-inbound.json b/docs/.generated/plugin-sdk-api-baseline/channel-inbound.json index 59084efcebe3..d1c6210f1570 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-inbound.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-inbound.json @@ -1 +1 @@ -{"contentHash":"d6c0e5bf1e49fc6e003221a3ff6daf951082742fa7e82215572456e4d4eaaf18","entrypoint":"channel-inbound","importSpecifier":"openclaw/plugin-sdk/channel-inbound"} +{"contentHash":"1934d2e58a1139d5f0fe9b69d231a9b1140a0a9f00f13c44ef36926e99d6d0cc","entrypoint":"channel-inbound","importSpecifier":"openclaw/plugin-sdk/channel-inbound"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-message.json b/docs/.generated/plugin-sdk-api-baseline/channel-message.json index 505d71483049..571e4e56af2b 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-message.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-message.json @@ -1 +1 @@ -{"contentHash":"f30a3ff93dab57ce1a6e73c10b027d2bb748968cd87cda27228654fc41811a03","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} +{"contentHash":"ad9dc515e2c9ed1c15397a9846c6212c56276c5dda24635be3f315312f077e43","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json index 251f4ea554dc..6e63230bb6da 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json @@ -1 +1 @@ -{"contentHash":"b6ef4ba8c3840141bff65a7fee3a5ea8efbe3da79696f5d59b41f8ccf1e32914","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} +{"contentHash":"29089a2b47826afc64a85979f3606d4140aa272a77e90247dd92e65bca3a2dd8","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json index 4da75b1b6b96..3c1e1c698bd6 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json @@ -1 +1 @@ -{"contentHash":"43afd1b1996e17f373e75c3922cbea6a0223782b0b68f6d05f7c29bbd83b8ebb","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} +{"contentHash":"1eda9bc8cdf2adff5b1c04f0d9eaafed8c448bccae1728ad7a6475040e48c960","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} diff --git a/docs/.generated/plugin-sdk-api-baseline/core.json b/docs/.generated/plugin-sdk-api-baseline/core.json index ceac45434780..f2423c7ed98a 100644 --- a/docs/.generated/plugin-sdk-api-baseline/core.json +++ b/docs/.generated/plugin-sdk-api-baseline/core.json @@ -1 +1 @@ -{"contentHash":"4d6021d0ae4ad15e1ce39d8700756ec415d604606ed538240c8f8aa9bf0acc37","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} +{"contentHash":"ca227941dce03110d71765ad1d2e8df89e30d09c19f664082d4e2a113937211b","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/discord.json b/docs/.generated/plugin-sdk-api-baseline/discord.json index a581faedc4ea..e984996cdaba 100644 --- a/docs/.generated/plugin-sdk-api-baseline/discord.json +++ b/docs/.generated/plugin-sdk-api-baseline/discord.json @@ -1 +1 @@ -{"contentHash":"17eaa6392ffdf071bbe104a7c5720892042a906109be42478dec03b8bf5291a0","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} +{"contentHash":"6de4593681bd8424e7334550612c4e1e9962e1a4dda50effc6890da7a4076fe5","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} diff --git a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json index f232b4541473..8879d0effadc 100644 --- a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json @@ -1 +1 @@ -{"contentHash":"176c5db037a1e5b685c0550aeee46186b3273e8da4bbb8a720a074596598e8cc","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} +{"contentHash":"225e30b4d18d4c77aee34623d9e69263835eddf690d0ad6d9dc1285e8f349d06","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json index 7c0976da00ab..c64cc8330183 100644 --- a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json +++ b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json @@ -1 +1 @@ -{"contentHash":"7bbbe7b8509abe241992eb632b1b484df2c270534f485ecf0f80e48b5671566a","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} +{"contentHash":"b156cd10587667ccf02b0fd7e066de0cf37cd219f0c07c8fb065c293e1f675de","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} diff --git a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json index 94e70da01e84..65f9fa9c219a 100644 --- a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json @@ -1 +1 @@ -{"contentHash":"00ae2e13016a7ba0ebd4baef8b34a2b3811e0221799f6351d2189f6e0ea694ba","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} +{"contentHash":"1e566fe360e6b82b1d31ded008160ddbfbc97713d3d55f1b9f3ba641825d537c","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json index 474c9c965de1..0ae521065c36 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json @@ -1 +1 @@ -{"contentHash":"e20acaab6a8d3d56b57a487168439da89adfe250f0474a4c53350424415ac498","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} +{"contentHash":"05d6916c82b9a5b512fd541e68a56040aee9a8a23019e6c70e8a62cdcee16716","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json index 0dd7bab53d6f..791f17163d87 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json @@ -1 +1 @@ -{"contentHash":"31e0fb8e73f98c8f69f8808aec8d8dc18fc2a074a21b9fc82414729fa1acceee","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} +{"contentHash":"0d68fc98d2c75f2dc4d74670b8d902000c7af2945b65aeae2f783a8e705675a7","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json index 1661414f0136..75abdbb72639 100644 --- a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json @@ -1 +1 @@ -{"contentHash":"4918ded36f8fc0701bd94e4be965577c1c035977e6c5d32db1c17862775d6318","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} +{"contentHash":"34eb7210106298e9efc89a2891438dd05e198a1b6a7510f0c948c4f916b752ca","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json index bc034e25fcc5..29e0e38c38df 100644 --- a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json +++ b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json @@ -1 +1 @@ -{"contentHash":"cd199186dee1148dc53d05710cb9785fdcff475bedbc92f5c18b5ddca675dbe7","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} +{"contentHash":"e573cfb3d9ee7c9f79aee3f425fd804953e9df34283196006033dea6ee302396","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} diff --git a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json index 92ab4d7a41d3..e154f726fa75 100644 --- a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json +++ b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json @@ -1 +1 @@ -{"contentHash":"265be26af18bed1c86ddc4636df78ac2f064848dcfc9e9da8e05842c69750ba4","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} +{"contentHash":"baecdbe479ff6b3a7ae95d67ce3539d61acd424cea71692a04276972884ea372","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index abd4503c2e9b..b7782a3e3eb6 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -496,7 +496,7 @@ Capability toggles stay disabled until the Gateway, session, and runtime config - Consecutive duplicate text-only messages render as one bubble with a count badge. Messages that carry images, attachments, tool output, or canvas previews are left uncollapsed. - User-message bubbles carry transcript actions: a hover rewind button (confirm popover with a "Don't ask again" option) plus right-click **Rewind to here** and **Fork from here**. Rewind repoints the session to the state just before that message and returns its text to the composer for edit and resend (`sessions.rewind`, `operator.admin`); fork creates a new session from the active-path prefix before the message, opens it, and seeds its composer with the same text (`sessions.fork`, `operator.write`). Both actions disable with an explanatory tooltip while the agent is working, apply only to persisted user messages, and are rejected for sessions whose conversation is owned by an external agent harness. Rewind moves chat context only — files and other tool side effects are not reverted — and the pre-rewind transcript remains preserved in the append-only session store. When that store contains multiple transcript branches, the chat title bar shows a branch menu with each branch's latest message, message count, and recency; selecting an inactive branch switches the current session back to that preserved path (`sessions.branches.list`, `operator.read`; `sessions.branches.switch`, `operator.admin`). Branch switching is also unavailable while the agent is working, and selecting the already-active branch is a typed no-op error at the RPC boundary. - When a session's checkout sits on a non-default branch of a GitHub repository, the chat view pins pull request chips above the composer: PR number, repo, branch, diff counts, a CI pill, and draft/merged/closed state, each linking to the PR. The row shows at most two chips — live (open/draft) PRs first — and a "Show more" button reveals collapsed merged/closed history. The CI pill opens a small CI monitoring popover with passed/failed/running/skipped check counts and a link to the PR's checks page. The Gateway polls only sessions visible in a connected Control UI and pushes changed snapshots through `controlUi.sessionPullRequests.changed`; it reuses `GH_TOKEN`/`GITHUB_TOKEN` when set. When the GitHub API rate limit is hit, chips keep the last known status and show a warning that the status may be out of date; dismissing a chip hides it for that session in the current browser profile. Before any PR exists, the row shows the branch itself — repo, branch name, and the +/− size of the diff against the default-branch merge base (committed and uncommitted work). Once the pushed branch has commits to compare, the row adds a Create PR button that opens GitHub's new-pull-request page; before that, a session with changed files (committed, uncommitted, or untracked) still gets the row without the button. The row hides itself while an open or draft PR exists; once the branch's PR is merged and the pushed tip still matches the merged head, the row disappears too (returning without the Create PR button only when new local work appears, and with it once new commits are pushed past the merged head). The branch row comes from local git only, so it stays available while GitHub is rate limited and carries the same stale-status warning, since "no PR found" cannot be trusted until the limit resets. - - The session diff panel shows what a session's checkout actually changed: the branch button in the workspace rail or chat title bar opens the detail panel with a per-file diff of branch, uncommitted, and untracked work against the checkout's default-branch merge base — status dot, rename arrow, per-file +/− counts, collapsible files, and "N unmodified lines" markers between hunks. Diffs are computed server-side through the `sessions.diff` Gateway method (`operator.read` scope); binary and oversized files degrade to stats-only entries, and the button only appears when the connected Gateway advertises `sessions.diff`. + - The session diff panel shows what a session's checkout actually changed: the branch button in the workspace rail or chat title bar opens a dense per-file viewer with normalized added/deleted/modified counts, collapsible files, wrapping and unified/split layouts, file copy/open/editor actions, and "N unmodified lines" markers between hunks. The footer switches between all changes, uncommitted work, and individual commits while showing how far the branch is ahead of its merge base; committed branches also provide a copyable local sync command. Diffs are computed server-side through the `sessions.diff` Gateway method (`operator.read` scope); binary and oversized files degrade to stats-only entries, and the button only appears when the connected Gateway advertises `sessions.diff`. - Every Chat pane has a title bar. Click the session title to rename it; the workspace chip copies the checkout path or branch and can reveal local Gateway workspaces in the host file manager. Remote and exec-node sessions keep copy actions but hide reveal. - The thread workspace rail in each Chat pane lists thread files, project files, and artifacts. It docks to the pane's right edge by default; drag its header (or use the dock button) to move it to the bottom, and the choice is stored in the current browser profile. A collapsed rail takes no space at all: reopen it with ⇧⌘B or the files toggle in the title bar, which carries a changed-file count badge. The separate file, tool, and Canvas detail panel is unaffected. - File paths recognized in chat messages read as their basename with a small glyph for the file type in front — a Markdown page, a `package.json` manifest, a TypeScript source, a `.tsx` component, a config or data file, a shell script, and an image each get their own mark, and anything else falls back to a plain document. When two links in the same message share a basename, each keeps just enough of its trailing path to stay distinct. The full path stays on the link: it is what the tooltip shows, what opens in the file panel, and what the message's **Copy** action returns, since copy hands back the original Markdown. Labels you write yourself in a `[label](path)` link are never rewritten. The glyph is drawn from the bundled icon set, never fetched from the network, and is decorative only: it is not read by screen readers and is not part of copied text. Text that is not a recognizable path — anything carrying spaces, parentheses, a `#` fragment, or a `?` query — stays plain prose. diff --git a/packages/gateway-protocol/src/index.ts b/packages/gateway-protocol/src/index.ts index a4ffa3eeba41..541c47409065 100644 --- a/packages/gateway-protocol/src/index.ts +++ b/packages/gateway-protocol/src/index.ts @@ -244,8 +244,10 @@ export { SessionsFilesListResultSchema, SessionsFilesRevealParamsSchema, SessionsFilesRevealResultSchema, + SessionDiffCommitSchema, SessionDiffFileSchema, SessionDiffFileStatusSchema, + SessionDiffScopeSchema, SessionsDiffParamsSchema, SessionsDiffResultSchema, SessionsCompactionListParamsSchema, diff --git a/packages/gateway-protocol/src/schema/protocol-schema-fragment-sessions-lifecycle.ts b/packages/gateway-protocol/src/schema/protocol-schema-fragment-sessions-lifecycle.ts index f58f0f2a2d59..2255ee5dbe3b 100644 --- a/packages/gateway-protocol/src/schema/protocol-schema-fragment-sessions-lifecycle.ts +++ b/packages/gateway-protocol/src/schema/protocol-schema-fragment-sessions-lifecycle.ts @@ -33,6 +33,8 @@ export const SessionLifecycleProtocolSchemas = { SessionsFilesSetResult: sessions.SessionsFilesSetResultSchema, SessionDiffFileStatus: sessions.SessionDiffFileStatusSchema, SessionDiffFile: sessions.SessionDiffFileSchema, + SessionDiffCommit: sessions.SessionDiffCommitSchema, + SessionDiffScope: sessions.SessionDiffScopeSchema, SessionsDiffParams: sessions.SessionsDiffParamsSchema, SessionsDiffResult: sessions.SessionsDiffResultSchema, SessionWorktreeInfo: sessions.SessionWorktreeInfoSchema, diff --git a/packages/gateway-protocol/src/schema/sessions.ts b/packages/gateway-protocol/src/schema/sessions.ts index 461ffe2e633a..cd69c84831df 100644 --- a/packages/gateway-protocol/src/schema/sessions.ts +++ b/packages/gateway-protocol/src/schema/sessions.ts @@ -321,10 +321,25 @@ export const SessionDiffFileSchema = closedObject({ truncated: Type.Optional(Type.Boolean()), }); +/** One commit shown in session diff branch metadata. */ +export const SessionDiffCommitSchema = closedObject({ + sha: NonEmptyString, + subject: Type.String(), +}); + +/** Selects the session checkout state represented by the diff. */ +export const SessionDiffScopeSchema = Type.Union([ + Type.Literal("all"), + Type.Literal("uncommitted"), + Type.Literal("commit"), +]); + /** Reads the git diff of a session checkout against its base branch. */ export const SessionsDiffParamsSchema = closedObject({ sessionKey: NonEmptyString, agentId: Type.Optional(NonEmptyString), + scope: Type.Optional(SessionDiffScopeSchema), + commit: Type.Optional(NonEmptyString), }); /** Branch + working-tree diff for one session checkout. */ @@ -334,12 +349,22 @@ export const SessionsDiffResultSchema = closedObject({ branch: Type.Optional(NonEmptyString), /** Display label of the diff base: the default branch name or "HEAD". */ baseRef: Type.Optional(NonEmptyString), + /** Number of commits between the resolved branch merge base and HEAD. */ + aheadCount: Type.Optional(Type.Integer({ minimum: 0 })), + /** Newest-first commits between the resolved branch merge base and HEAD. */ + commits: Type.Optional(Type.Array(SessionDiffCommitSchema, { maxItems: 50 })), + /** The resolved branch merge-base commit. */ + mergeBase: Type.Optional(SessionDiffCommitSchema), files: Type.Array(SessionDiffFileSchema), additions: Type.Integer({ minimum: 0 }), deletions: Type.Integer({ minimum: 0 }), truncated: Type.Optional(Type.Boolean()), unavailableReason: Type.Optional( - Type.Union([Type.Literal("unknown_session"), Type.Literal("not_git")]), + Type.Union([ + Type.Literal("unknown_session"), + Type.Literal("not_git"), + Type.Literal("unknown_commit"), + ]), ), }); @@ -823,5 +848,7 @@ export type SessionsFilesRevealParams = Static; export type SessionDiffFileStatus = Static; export type SessionDiffFile = Static; +export type SessionDiffCommit = Static; +export type SessionDiffScope = Static; export type SessionsDiffParams = Static; export type SessionsDiffResult = Static; diff --git a/src/gateway/server-methods/sessions-diff.test.ts b/src/gateway/server-methods/sessions-diff.test.ts index d78163d0faa5..8c3daa622d64 100644 --- a/src/gateway/server-methods/sessions-diff.test.ts +++ b/src/gateway/server-methods/sessions-diff.test.ts @@ -197,6 +197,7 @@ describe("loadSessionDiff", () => { fs.writeFileSync(path.join(repoRoot, "a.txt"), "one\n"); git(repoRoot, "add", "."); git(repoRoot, "commit", "-qm", "init"); + const rootCommit = git(repoRoot, "rev-parse", "HEAD").trim(); fs.writeFileSync(path.join(repoRoot, "a.txt"), "one\nmore\n"); mockSession(repoRoot); @@ -205,6 +206,92 @@ describe("loadSessionDiff", () => { expect(result.baseRef).toBe("HEAD"); expect(result.files).toHaveLength(1); expect(result.files[0]?.additions).toBe(1); + + const committed = await loadSessionDiff({ + sessionKey: "agent:main:s1", + scope: "commit", + commit: rootCommit, + }); + expect(committed.unavailableReason).toBe("unknown_commit"); + expect(committed.files).toEqual([]); + }); + + it("scopes branch, working-tree, and commit diffs with branch metadata", async () => { + initRepo(repoRoot); + fs.writeFileSync(path.join(repoRoot, "base.txt"), "base\n"); + git(repoRoot, "add", "."); + git(repoRoot, "commit", "-qm", "base"); + const mergeBase = git(repoRoot, "rev-parse", "HEAD").trim(); + git(repoRoot, "checkout", "-qb", "sibling"); + fs.writeFileSync(path.join(repoRoot, "sibling.txt"), "sibling commit\n"); + git(repoRoot, "add", "."); + git(repoRoot, "commit", "-qm", "sibling change"); + const siblingCommit = git(repoRoot, "rev-parse", "HEAD").trim(); + git(repoRoot, "checkout", "-q", "main"); + git(repoRoot, "checkout", "-qb", "feature"); + + fs.writeFileSync(path.join(repoRoot, "first.txt"), "first commit\n"); + git(repoRoot, "add", "."); + git(repoRoot, "commit", "-qm", "first change"); + const firstCommit = git(repoRoot, "rev-parse", "HEAD").trim(); + fs.writeFileSync(path.join(repoRoot, "second.txt"), "second commit\n"); + git(repoRoot, "add", "."); + git(repoRoot, "commit", "-qm", "second change"); + const secondCommit = git(repoRoot, "rev-parse", "HEAD").trim(); + + fs.appendFileSync(path.join(repoRoot, "second.txt"), "working tree\n"); + fs.writeFileSync(path.join(repoRoot, "loose.txt"), "untracked\n"); + mockSession(repoRoot); + + const all = await loadSessionDiff({ sessionKey: "agent:main:s1" }); + expect(all.files.map((file) => file.path)).toEqual(["first.txt", "loose.txt", "second.txt"]); + expect(all.aheadCount).toBe(2); + expect(all.commits).toEqual([ + { sha: git(repoRoot, "rev-parse", "--short", secondCommit).trim(), subject: "second change" }, + { sha: git(repoRoot, "rev-parse", "--short", firstCommit).trim(), subject: "first change" }, + ]); + expect(all.mergeBase).toEqual({ + sha: git(repoRoot, "rev-parse", "--short", mergeBase).trim(), + subject: "base", + }); + + const uncommitted = await loadSessionDiff({ + sessionKey: "agent:main:s1", + scope: "uncommitted", + }); + expect(uncommitted.files.map((file) => file.path)).toEqual(["loose.txt", "second.txt"]); + expect(uncommitted.files.find((file) => file.path === "second.txt")?.patch).toContain( + "+working tree", + ); + + const baseline = await captureSessionDiffBaseline({ cwd: repoRoot, sessionId: "s1" }); + mockSession(repoRoot, { sessionDiffBaseline: baseline }); + const committed = await loadSessionDiff({ + sessionKey: "agent:main:s1", + scope: "commit", + commit: firstCommit, + }); + expect(committed.files.map((file) => file.path)).toEqual(["first.txt"]); + expect(committed.files[0]?.patch).toContain("+first commit"); + expect(committed.files[0]?.untracked).toBeUndefined(); + + for (const commit of [siblingCommit, mergeBase]) { + const outsideAdvertisedHistory = await loadSessionDiff({ + sessionKey: "agent:main:s1", + scope: "commit", + commit, + }); + expect(outsideAdvertisedHistory.unavailableReason).toBe("unknown_commit"); + expect(outsideAdvertisedHistory.files).toEqual([]); + } + + const unknown = await loadSessionDiff({ + sessionKey: "agent:main:s1", + scope: "commit", + commit: "not-a-commit", + }); + expect(unknown.unavailableReason).toBe("unknown_commit"); + expect(unknown.files).toEqual([]); }); it("never executes configured textconv drivers from the read RPC", async () => { @@ -363,19 +450,27 @@ describe("loadSessionDiff", () => { }); it("rejects invalid params through the handler", async () => { - const calls: Array<{ ok: boolean; payload?: unknown; error?: unknown }> = []; - await sessionsDiffHandlers["sessions.diff"]?.({ - req: { type: "req", id: "sessions.diff", method: "sessions.diff", params: {} }, - params: {}, - client: null, - isWebchatConnect: () => false, - respond: (ok: boolean, payload?: unknown, error?: unknown) => { - calls.push({ ok, payload, error }); - }, - context: { getRuntimeConfig: () => ({}) } as never, - }); - expect(calls).toHaveLength(1); - expect(calls[0]?.ok).toBe(false); + const invalidParams = [ + {}, + { sessionKey: "agent:main:s1", scope: "commit" }, + { sessionKey: "agent:main:s1", scope: "all", commit: "HEAD" }, + { sessionKey: "agent:main:s1", scope: "uncommitted", commit: "HEAD" }, + ]; + for (const params of invalidParams) { + const calls: Array<{ ok: boolean; payload?: unknown; error?: unknown }> = []; + await sessionsDiffHandlers["sessions.diff"]?.({ + req: { type: "req", id: "sessions.diff", method: "sessions.diff", params }, + params, + client: null, + isWebchatConnect: () => false, + respond: (ok: boolean, payload?: unknown, error?: unknown) => { + calls.push({ ok, payload, error }); + }, + context: { getRuntimeConfig: () => ({}) } as never, + }); + expect(calls).toHaveLength(1); + expect(calls[0]?.ok).toBe(false); + } }); }); diff --git a/src/gateway/server-methods/sessions-diff.ts b/src/gateway/server-methods/sessions-diff.ts index c93b0a06a80c..0d78b48ccc15 100644 --- a/src/gateway/server-methods/sessions-diff.ts +++ b/src/gateway/server-methods/sessions-diff.ts @@ -2,6 +2,8 @@ // working-tree state captured when the logical session started. import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce"; import { + ErrorCodes, + errorShape, validateSessionsDiffParams, type SessionsDiffParams, type SessionsDiffResult, @@ -51,9 +53,24 @@ export async function loadSessionDiff(params: SessionsDiffParams): Promise Promise; + +/** Picks the merge base used for branch-relative session diffs. */ +export async function resolveSessionDiffBase(params: { + branch: string | undefined; + gitOut: GitOutput; + root: string; +}): Promise<{ base: string; baseRef: string }> { + const defaultRef = await params.gitOut(params.root, [ + "symbolic-ref", + "--short", + "refs/remotes/origin/HEAD", + ]); + const remoteDefault = defaultRef?.trim() || null; + const defaultShort = remoteDefault?.replace(/^origin\//, ""); + if (remoteDefault && defaultShort && params.branch && params.branch !== defaultShort) { + const mergeBase = await params.gitOut(params.root, ["merge-base", remoteDefault, "HEAD"]); + if (mergeBase?.trim()) { + return { base: mergeBase.trim(), baseRef: defaultShort }; + } + } + // Plain clones without origin/HEAD still get a branch-relative diff. + if (params.branch && params.branch !== "main" && params.branch !== "master") { + for (const candidate of ["main", "master"]) { + const verified = await params.gitOut(params.root, [ + "rev-parse", + "--verify", + "--quiet", + candidate, + ]); + if (verified?.trim()) { + const mergeBase = await params.gitOut(params.root, ["merge-base", candidate, "HEAD"]); + if (mergeBase?.trim()) { + return { base: mergeBase.trim(), baseRef: candidate }; + } + } + } + } + return { base: "HEAD", baseRef: "HEAD" }; +} + +/** Resolves the repository-format-specific empty tree without writing it. */ +export async function resolveSessionDiffEmptyTree( + root: string, +): Promise<{ base: string; baseRef?: string } | null> { + try { + const result = await runGit(root, ["hash-object", "-t", "tree", "--stdin"], { input: "" }); + const emptyTree = result.code === 0 ? result.stdout.trim() : ""; + return emptyTree ? { base: emptyTree } : null; + } catch { + return null; + } +} + +type BranchDiffMetadata = Pick; + +function parseCommitRecord(line: string): NonNullable | undefined { + const separator = line.indexOf("\0"); + if (separator <= 0) { + return undefined; + } + return { sha: line.slice(0, separator), subject: line.slice(separator + 1) }; +} + +function parseCommitRecords(text: string): NonNullable { + return text + .split("\n") + .map(parseCommitRecord) + .filter( + (record): record is NonNullable => record !== undefined, + ); +} + +/** Loads the bounded branch history metadata shared by every diff scope. */ +export async function loadSessionDiffBranchMetadata(params: { + base: string; + gitOut: GitOutput; + head: string; + root: string; +}): Promise { + if (params.base === "HEAD" || params.base === params.head) { + return {}; + } + const range = `${params.base}..HEAD`; + const [aheadText, commitsText, mergeBaseText] = await Promise.all([ + params.gitOut(params.root, ["rev-list", "--count", range]), + params.gitOut(params.root, ["log", "--max-count=50", "--format=%h%x00%s", range, "--"]), + params.gitOut(params.root, ["show", "--no-patch", "--format=%h%x00%s", params.base, "--"]), + ]); + const normalizedAhead = aheadText?.trim(); + const aheadCount = + normalizedAhead && /^\d+$/.test(normalizedAhead) + ? Number.parseInt(normalizedAhead, 10) + : undefined; + const mergeBase = mergeBaseText ? parseCommitRecords(mergeBaseText)[0] : undefined; + return { + ...(aheadCount !== undefined ? { aheadCount } : {}), + ...(commitsText !== null ? { commits: parseCommitRecords(commitsText) } : {}), + ...(mergeBase ? { mergeBase } : {}), + }; +} diff --git a/src/sessions/session-diff.ts b/src/sessions/session-diff.ts index e8a93cef1da2..c66456a65942 100644 --- a/src/sessions/session-diff.ts +++ b/src/sessions/session-diff.ts @@ -11,6 +11,11 @@ import type { import { runGit } from "../agents/worktrees/git.js"; import type { SessionDiffBaseline } from "../config/sessions/types.js"; import { runCommandBuffered } from "../process/exec.js"; +import { + loadSessionDiffBranchMetadata, + resolveSessionDiffBase, + resolveSessionDiffEmptyTree, +} from "./session-diff-revisions.js"; const MAX_FILES = 500; const MAX_UNTRACKED_FILES = 100; @@ -207,58 +212,6 @@ function takePatch( return { patch: chunk }; } -/** - * Picks the ref the session diff is computed against: merge-base with the - * remote default branch when on a feature branch, otherwise HEAD so sessions - * on the default branch still surface uncommitted work. - */ -async function resolveDiffBase( - root: string, - branch: string | undefined, -): Promise<{ base: string; baseRef: string }> { - const defaultRef = await gitOut(root, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]); - const remoteDefault = defaultRef?.trim() || null; - const defaultShort = remoteDefault?.replace(/^origin\//, ""); - if (remoteDefault && defaultShort && branch && branch !== defaultShort) { - const mergeBase = await gitOut(root, ["merge-base", remoteDefault, "HEAD"]); - if (mergeBase?.trim()) { - return { base: mergeBase.trim(), baseRef: defaultShort }; - } - } - // No usable remote default: try a local main/master so plain clones still - // get a branch-relative diff instead of only uncommitted changes. - if (branch && branch !== "main" && branch !== "master") { - for (const candidate of ["main", "master"]) { - const verified = await gitOut(root, ["rev-parse", "--verify", "--quiet", candidate]); - if (verified?.trim()) { - const mergeBase = await gitOut(root, ["merge-base", candidate, "HEAD"]); - if (mergeBase?.trim()) { - return { base: mergeBase.trim(), baseRef: candidate }; - } - } - } - } - return { base: "HEAD", baseRef: "HEAD" }; -} - -/** - * Diff base for a repo before its first commit: the empty-tree object id, so - * `git diff ` reports staged/index files as additions. `hash-object` - * derives the id for the repo's object format (SHA-1 vs SHA-256) and does not - * write to the object DB. baseRef stays undefined — there is no named base. - */ -async function resolveUnbornDiffBase( - root: string, -): Promise<{ base: string; baseRef?: string } | null> { - try { - const result = await runGit(root, ["hash-object", "-t", "tree", "--stdin"], { input: "" }); - const emptyTree = result.code === 0 ? result.stdout.trim() : ""; - return emptyTree ? { base: emptyTree } : null; - } catch { - return null; - } -} - async function collectUntrackedFiles( root: string, realRoot: string, @@ -336,11 +289,11 @@ async function collectUntrackedFiles( async function collectTrackedFiles( root: string, realRoot: string, - base: string, + revisions: readonly [base: string] | readonly [base: string, target: string], budget: PatchBudget, ): Promise<{ files: SessionDiffFile[]; truncated: boolean }> { - const diffArgs = ["diff", "-M", base]; - const nameStatus = await gitOut(root, [...diffArgs, "--name-status", "-z"]); + const diffArgs = (options: string[]) => ["diff", "-M", ...options, ...revisions, "--"]; + const nameStatus = await gitOut(root, diffArgs(["--name-status", "-z"])); if (nameStatus === null) { return { files: [], truncated: false }; } @@ -348,7 +301,7 @@ async function collectTrackedFiles( if (entries.length === 0) { return { files: [], truncated: false }; } - const numstatText = (await gitOut(root, [...diffArgs, "--numstat", "-z"])) ?? ""; + const numstatText = (await gitOut(root, diffArgs(["--numstat", "-z"]))) ?? ""; const numstat = parseNumstatZ(numstatText); const totalChangedLines = [...numstat.values()].reduce( (sum, entry) => sum + entry.additions + entry.deletions, @@ -359,13 +312,7 @@ async function collectTrackedFiles( const patchText = totalChangedLines > MAX_TOTAL_CHANGED_LINES ? null - : await gitOut(root, [ - ...diffArgs, - "--patch", - "--no-color", - "--no-ext-diff", - "--no-textconv", - ]); + : await gitOut(root, diffArgs(["--patch", "--no-color", "--no-ext-diff", "--no-textconv"])); const chunks = patchText === null ? new Map() : splitPatchByFile(patchText); const truncated = entries.length > MAX_FILES; const files: SessionDiffFile[] = []; @@ -387,11 +334,12 @@ async function collectTrackedFiles( files.push(file); continue; } - // Deleted files diff against the object DB (no filesystem read); every - // other status reads the working-tree file, so hardlink-guard it before - // returning content the bulk diff already buffered server-side. + // Like the deleted-file exemption, two-revision commit diffs read every + // path from the object DB. Only working-tree content needs the hardlink guard. const safe = - entry.status === "deleted" || (await isPatchableWorkingTreePath(realRoot, entry.path)); + revisions.length === 2 || + entry.status === "deleted" || + (await isPatchableWorkingTreePath(realRoot, entry.path)); if (!safe) { file.truncated = true; files.push(file); @@ -409,10 +357,12 @@ async function collectTrackedFiles( return { files, truncated }; } -export async function loadCheckoutDiff(params: { - cwd: string; - sessionKey: string; -}): Promise { +type CheckoutDiffParams = { cwd: string; sessionKey: string } & ( + | { scope?: "all" | "uncommitted"; commit?: never } + | { scope: "commit"; commit: string } +); + +export async function loadCheckoutDiff(params: CheckoutDiffParams): Promise { const empty = ( unavailableReason?: NonNullable, ): SessionsDiffResult => ({ @@ -431,19 +381,71 @@ export async function loadCheckoutDiff(params: { const realRoot = await fs.realpath(root).catch(() => root); const branchOut = (await gitOut(root, ["rev-parse", "--abbrev-ref", "HEAD"]))?.trim(); const branch = branchOut && branchOut !== "HEAD" ? branchOut : undefined; + const head = (await gitOut(root, ["rev-parse", "--verify", "--quiet", "HEAD"]))?.trim(); + const branchBase = head + ? await resolveSessionDiffBase({ branch, gitOut, root }) + : await resolveSessionDiffEmptyTree(root); + const metadata = + head && branchBase + ? await loadSessionDiffBranchMetadata({ base: branchBase.base, gitOut, head, root }) + : {}; + const repositoryFields = { + sessionKey: params.sessionKey, + root, + ...(branch ? { branch } : {}), + ...(branchBase?.baseRef ? { baseRef: branchBase.baseRef } : {}), + ...metadata, + }; + const unknownCommit = (): SessionsDiffResult => ({ + ...repositoryFields, + files: [], + additions: 0, + deletions: 0, + unavailableReason: "unknown_commit", + }); + const scope = params.scope ?? "all"; + let revisions: readonly [string] | readonly [string, string] | undefined; + if (scope === "commit") { + if (!head || !branchBase || branchBase.base === "HEAD" || branchBase.base === head) { + return unknownCommit(); + } + const commit = ( + await gitOut(root, [ + "rev-parse", + "--verify", + "--quiet", + "--end-of-options", + `${params.commit}^{commit}`, + ]) + )?.trim(); + if (!commit) { + return unknownCommit(); + } + // Commit scope is fenced to the advertised merge-base..HEAD history so an + // operator.read client cannot read arbitrary commits from the object database. + const isCommitInHeadHistory = + (await gitOut(root, ["merge-base", "--is-ancestor", commit, "HEAD"], [0])) !== null; + const isCommitInBaseHistory = + (await gitOut(root, ["merge-base", "--is-ancestor", commit, branchBase.base], [0])) !== null; + if (!isCommitInHeadHistory || isCommitInBaseHistory) { + return unknownCommit(); + } + const parent = (await gitOut(root, ["rev-parse", "--verify", "--quiet", `${commit}^`]))?.trim(); + const commitBase = parent ? { base: parent } : await resolveSessionDiffEmptyTree(root); + revisions = commitBase ? [commitBase.base, commit] : undefined; + } else if (scope === "uncommitted") { + revisions = head ? ["HEAD"] : branchBase ? [branchBase.base] : undefined; + } else { + revisions = branchBase ? [branchBase.base] : undefined; + } const budget: PatchBudget = { remaining: MAX_TOTAL_PATCH_BYTES }; - // Repos before their first commit have no HEAD, so diff the index/worktree - // against the empty tree to surface staged files (the untracked scan below - // only covers files git does not track yet). hash-object derives the empty - // tree id for the repo's object format without writing to the object DB. - const hasHead = (await gitOut(root, ["rev-parse", "--verify", "--quiet", "HEAD"])) !== null; - const baseInfo = hasHead - ? await resolveDiffBase(root, branch) - : await resolveUnbornDiffBase(root); - const tracked = baseInfo - ? await collectTrackedFiles(root, realRoot, baseInfo.base, budget) + const tracked = revisions + ? await collectTrackedFiles(root, realRoot, revisions, budget) : { files: [], truncated: false }; - const untracked = await collectUntrackedFiles(root, realRoot, budget); + const untracked = + scope === "commit" + ? { files: [], truncated: false } + : await collectUntrackedFiles(root, realRoot, budget); const files = [...tracked.files, ...untracked.files].toSorted((a, b) => a.path.localeCompare(b.path), ); @@ -452,10 +454,7 @@ export async function loadCheckoutDiff(params: { const truncated = tracked.truncated || untracked.truncated || files.some((file) => file.truncated === true); return { - sessionKey: params.sessionKey, - root, - ...(branch ? { branch } : {}), - ...(baseInfo?.baseRef ? { baseRef: baseInfo.baseRef } : {}), + ...repositoryFields, files, additions, deletions, @@ -611,8 +610,8 @@ async function collectBaselineCandidates(params: { const branch = branchOut && branchOut !== "HEAD" ? branchOut : undefined; const hasHead = (await gitOut(root, ["rev-parse", "--verify", "--quiet", "HEAD"])) !== null; const baseInfo = hasHead - ? await resolveDiffBase(root, branch) - : await resolveUnbornDiffBase(root); + ? await resolveSessionDiffBase({ branch, gitOut, root }) + : await resolveSessionDiffEmptyTree(root); const trackedText = baseInfo ? await gitOutForBaseline(root, ["diff", "-M", baseInfo.base, "--name-status", "-z"]) : ""; diff --git a/ui/src/e2e/chat-session-diff.e2e.test.ts b/ui/src/e2e/chat-session-diff.e2e.test.ts index afd6489ec9f3..76f9e4ce9521 100644 --- a/ui/src/e2e/chat-session-diff.e2e.test.ts +++ b/ui/src/e2e/chat-session-diff.e2e.test.ts @@ -84,40 +84,99 @@ describeControlUiE2e("session diff panel", () => { it("opens the diff sidebar with per-file patches and gap markers", async () => { const context = await newBrowserContext(); const page = await context.newPage(); - await installMockGateway(page, { + const metadata = { + aheadCount: 2, + commits: [ + { sha: "def5678", subject: "Second feature change" }, + { sha: "abc1234", subject: "First feature change" }, + ], + mergeBase: { sha: "0011223", subject: "Initial commit" }, + }; + const gateway = await installMockGateway(page, { featureMethods: ["chat.metadata", "chat.startup", "sessions.diff"], methodResponses: { "sessions.diff": { - sessionKey: "main", - root: "/tmp/checkout", - branch: "feature/panel", - baseRef: "main", - files: [ + cases: [ { - path: "src/app.ts", - status: "modified", - additions: 2, - deletions: 1, - patch: APP_PATCH, + match: { scope: "uncommitted" }, + response: { + sessionKey: "main", + root: "/tmp/checkout", + branch: "feature/panel", + baseRef: "main", + ...metadata, + files: [ + { + path: "notes.md", + status: "added", + additions: 2, + deletions: 0, + untracked: true, + patch: NOTES_PATCH, + }, + ], + additions: 2, + deletions: 0, + }, }, { - path: "notes.md", - status: "added", - additions: 2, - deletions: 0, - untracked: true, - patch: NOTES_PATCH, + match: { scope: "commit", commit: "abc1234" }, + response: { + sessionKey: "main", + root: "/tmp/checkout", + branch: "feature/panel", + baseRef: "main", + ...metadata, + files: [ + { + path: "src/app.ts", + status: "modified", + additions: 2, + deletions: 1, + patch: APP_PATCH, + }, + ], + additions: 2, + deletions: 1, + }, }, { - path: "logo.png", - status: "modified", - additions: 0, - deletions: 0, - binary: true, + match: { scope: "all" }, + response: { + sessionKey: "main", + root: "/tmp/checkout", + branch: "feature/panel", + baseRef: "main", + ...metadata, + files: [ + { + path: "src/app.ts", + status: "modified", + additions: 2, + deletions: 1, + patch: APP_PATCH, + }, + { + path: "notes.md", + status: "added", + additions: 2, + deletions: 0, + untracked: true, + patch: NOTES_PATCH, + }, + { + path: "logo.png", + status: "modified", + additions: 0, + deletions: 0, + binary: true, + }, + ], + additions: 4, + deletions: 1, + }, }, ], - additions: 4, - deletions: 1, }, }, }); @@ -130,14 +189,23 @@ describeControlUiE2e("session diff panel", () => { await expect .poll(() => panel.locator(".session-diff__branch-label").textContent()) .toBe("main → feature/panel"); + await expect + .poll(async () => + (await panel.locator(".session-diff__summary .chat-diffstat").textContent())?.replace( + /\s/g, + "", + ), + ) + .toBe("+3~1"); const files = panel.locator(".session-diff__file"); await expect.poll(() => files.count()).toBe(3); const modified = files.first(); await expect - .poll(() => modified.locator(".session-diff__path").textContent()) - .toContain("src/app.ts"); + .poll(() => modified.locator(".session-diff__filename").textContent()) + .toBe("app.ts"); + await expect.poll(() => modified.locator(".session-diff__directory").textContent()).toBe("src"); // Hunk starting at old line 10 renders a leading gap marker. await expect .poll(() => modified.locator(".chat-diff__row--skip").first().textContent()) @@ -156,11 +224,47 @@ describeControlUiE2e("session diff panel", () => { .poll(() => binary.locator(".session-diff__note").textContent()) .toContain("Binary file"); - // Collapsing a file hides its diff body. - await modified.locator(".session-diff__file-header").click(); - await expect.poll(() => modified.locator(".chat-diff").count()).toBe(0); - await modified.locator(".session-diff__file-header").click(); + await panel.getByRole("button", { name: "Change view options" }).click(); + await page.getByRole("menuitem", { name: "Switch to Split Diff" }).click(); + await expect.poll(() => modified.locator(".session-diff-split").count()).toBe(1); + await panel.getByRole("button", { name: "Change view options" }).click(); + await page.getByRole("menuitem", { name: "Switch to Unified Diff" }).click(); await expect.poll(() => modified.locator(".chat-diff").count()).toBe(1); + // View-only toggles reuse parsed patches and do not refetch the RPC. + await expect.poll(async () => (await gateway.getRequests("sessions.diff")).length).toBe(1); + + // Collapsing a file hides its diff body. + await modified.locator(".session-diff__file-toggle").click(); + await expect.poll(() => modified.locator(".chat-diff").count()).toBe(0); + await panel.getByRole("button", { name: "Refresh changes" }).click(); + await expect.poll(async () => (await gateway.getRequests("sessions.diff")).length).toBe(2); + // Refresh keeps the current collapse state instead of expanding every file. + await expect.poll(() => modified.locator(".chat-diff").count()).toBe(0); + await modified.locator(".session-diff__file-toggle").click(); + await expect.poll(() => modified.locator(".chat-diff").count()).toBe(1); + + await panel.getByRole("button", { name: "Choose change scope" }).click(); + await page + .locator('openclaw-session-diff-menu wa-dropdown-item[value="scope:uncommitted"]') + .click(); + await expect + .poll(() => panel.locator(".session-diff__section-title").textContent()) + .toBe("Uncommitted"); + await expect.poll(() => panel.locator(".session-diff__file").count()).toBe(1); + await expect + .poll(async () => (await gateway.getRequests("sessions.diff")).at(-1)?.params) + .toMatchObject({ scope: "uncommitted" }); + + await panel.getByRole("button", { name: "Choose change scope" }).click(); + await page + .locator('openclaw-session-diff-menu wa-dropdown-item[value="scope:commit:abc1234"]') + .click(); + await expect + .poll(() => panel.locator(".session-diff__section-title").textContent()) + .toBe("abc1234 First feature change"); + await expect + .poll(async () => (await gateway.getRequests("sessions.diff")).at(-1)?.params) + .toMatchObject({ scope: "commit", commit: "abc1234" }); }); it("hides the diff toggle until the workspace becomes a git checkout", async () => { diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts index 36703db25c4b..2d151f3cef94 100644 --- a/ui/src/i18n/locales/en.ts +++ b/ui/src/i18n/locales/en.ts @@ -5406,7 +5406,34 @@ export const en: TranslationMap = { empty: "No changes in this session's checkout.", notGit: "This session's workspace is not a git checkout.", unknownSession: "No workspace is associated with this session.", + unknownCommit: "This commit is no longer available in the session checkout.", disconnected: "Gateway is disconnected.", + allChanges: "All Changes", + uncommitted: "Uncommitted", + commitsAhead: "{count} commits ahead of {base}", + head: "HEAD", + mergeBase: "Merge Base", + scopeMenu: "Choose change scope", + sync: "Sync", + syncLocally: "Sync Locally", + syncDescription: + "Run this command in a local checkout to mirror this session's committed changes.", + copyCommand: "Copy sync command", + checkoutPath: "Checkout path", + branchName: "Branch name", + uncommittedStay: "Uncommitted changes stay in the session checkout.", + viewOptions: "Change view options", + collapseAll: "Collapse All", + expandAll: "Expand All", + enableWrapping: "Enable Wrapping", + disableWrapping: "Disable Wrapping", + switchSplit: "Switch to Split Diff", + switchUnified: "Switch to Unified Diff", + fileActions: "Actions for {path}", + copyPath: "Copy Path", + openFile: "Open File", + openInEditor: "Open in Editor", + revealInFileTree: "Reveal in File Tree", unmodifiedLines: "{count} unmodified lines", binaryFile: "Binary file", untracked: "untracked", diff --git a/ui/src/lib/chat/session-diff-split.test.ts b/ui/src/lib/chat/session-diff-split.test.ts new file mode 100644 index 000000000000..5f5c39b1cca2 --- /dev/null +++ b/ui/src/lib/chat/session-diff-split.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from "vitest"; +import { pairSessionDiffLines } from "./session-diff-split.ts"; +import type { DiffLine } from "./tool-call-diff.ts"; + +describe("pairSessionDiffLines", () => { + it("pairs uneven change runs and spans context and gap rows", () => { + const lines: DiffLine[] = [ + { kind: "ctx", lineNo: 3, text: "before" }, + { kind: "del", lineNo: 4, text: "old one" }, + { kind: "del", lineNo: 5, text: "old two" }, + { kind: "add", lineNo: 4, text: "new" }, + { kind: "skip", text: "8 unmodified lines" }, + ]; + + expect(pairSessionDiffLines(lines)).toEqual([ + { kind: "span", line: lines[0] }, + { kind: "pair", left: lines[1], right: lines[3] }, + { kind: "pair", left: lines[2] }, + { kind: "span", line: lines[4] }, + ]); + }); +}); diff --git a/ui/src/lib/chat/session-diff-split.ts b/ui/src/lib/chat/session-diff-split.ts new file mode 100644 index 000000000000..dcc68685c97a --- /dev/null +++ b/ui/src/lib/chat/session-diff-split.ts @@ -0,0 +1,44 @@ +import type { DiffLine } from "./tool-call-diff.ts"; + +export type SessionSplitDiffRow = + | { kind: "pair"; left?: DiffLine; right?: DiffLine } + | { kind: "span"; line: DiffLine }; + +/** Aligns each adjacent deletion/addition block while keeping context and gaps full-width. */ +export function pairSessionDiffLines(lines: readonly DiffLine[]): SessionSplitDiffRow[] { + const rows: SessionSplitDiffRow[] = []; + for (let index = 0; index < lines.length;) { + const line = lines[index]; + if (!line) { + break; + } + if (line.kind !== "add" && line.kind !== "del") { + rows.push({ kind: "span", line }); + index += 1; + continue; + } + + const deletions: DiffLine[] = []; + const additions: DiffLine[] = []; + while (index < lines.length) { + const changed = lines[index]; + if (changed?.kind === "del") { + deletions.push(changed); + } else if (changed?.kind === "add") { + additions.push(changed); + } else { + break; + } + index += 1; + } + const count = Math.max(deletions.length, additions.length); + for (let pairIndex = 0; pairIndex < count; pairIndex += 1) { + rows.push({ + kind: "pair", + ...(deletions[pairIndex] ? { left: deletions[pairIndex] } : {}), + ...(additions[pairIndex] ? { right: additions[pairIndex] } : {}), + }); + } + } + return rows; +} diff --git a/ui/src/pages/chat/components/chat-diff-render.ts b/ui/src/pages/chat/components/chat-diff-render.ts index f9103cc08714..5a4ee6c19e25 100644 --- a/ui/src/pages/chat/components/chat-diff-render.ts +++ b/ui/src/pages/chat/components/chat-diff-render.ts @@ -6,13 +6,24 @@ import { t } from "../../../i18n/index.ts"; import type { ToolCardOutcome } from "../../../lib/chat/chat-types.ts"; import type { DiffLine, DiffStat } from "../../../lib/chat/tool-call-diff.ts"; -export function renderDiffStatChips(stat: DiffStat) { - if (stat.added === 0 && stat.removed === 0) { +export function renderDiffStatChips(stat: DiffStat & { modified?: number }) { + // Tool cards omit `modified`; keep their original template byte-for-byte. + if (stat.modified === undefined) { + if (stat.added === 0 && stat.removed === 0) { + return nothing; + } + return html` + ${stat.added > 0 ? html`+${stat.added}` : nothing} + ${stat.removed > 0 ? html`-${stat.removed}` : nothing} + `; + } + if (stat.added === 0 && stat.removed === 0 && !stat.modified) { return nothing; } return html` ${stat.added > 0 ? html`+${stat.added}` : nothing} ${stat.removed > 0 ? html`-${stat.removed}` : nothing} + ${stat.modified > 0 ? html`~${stat.modified}` : nothing} `; } diff --git a/ui/src/pages/chat/components/chat-session-workspace.ts b/ui/src/pages/chat/components/chat-session-workspace.ts index c975f5ea0c81..ed5952cc02a6 100644 --- a/ui/src/pages/chat/components/chat-session-workspace.ts +++ b/ui/src/pages/chat/components/chat-session-workspace.ts @@ -837,15 +837,18 @@ function buildSessionDiffSidebarContent(state: SessionWorkspaceHost): SidebarCon const sessionKey = state.sessionKey; return { kind: "session-diff", - load: async () => { + load: async (scope) => { if (!state.client) { throw new Error(t("chat.sessionDiff.disconnected")); } return await state.client.request("sessions.diff", { sessionKey, ...scopedAgentParamsForSession(state, sessionKey), + ...scope, }); }, + openFile: (path) => openFile(state, getWorkspaceState(state), path), + revealFile: (path) => revealSessionWorkspaceFile(state, path), }; } diff --git a/ui/src/pages/chat/components/chat-sidebar.ts b/ui/src/pages/chat/components/chat-sidebar.ts index 0fe6841c68df..52006938c0f3 100644 --- a/ui/src/pages/chat/components/chat-sidebar.ts +++ b/ui/src/pages/chat/components/chat-sidebar.ts @@ -81,6 +81,8 @@ type SessionDiffSidebarContent = { kind: "session-diff"; /** Fetches a fresh sessions.diff snapshot; the panel refetches on refresh. */ load: SessionDiffLoader; + openFile?: (path: string) => void; + revealFile?: (path: string) => void; rawText?: string | null; fullMessageRequest?: SidebarFullMessageRequest; unavailableReason?: DetailUnavailableReason | null; @@ -590,7 +592,11 @@ function renderMarkdownSidebar(props: MarkdownSidebarProps) { ? content.kind === "file" ? renderFileSidebarContent(content, props.onViewRawText, props.fileView) : content.kind === "session-diff" - ? html`` + ? html`` : content.kind === "canvas" ? html`
@@ -1335,7 +1341,9 @@ class ChatDetailPanel extends OpenClawLightDomElement { // Markdown previews and file editors need a bounded host wrapper so their // inner content can shrink and scroll. Content-sized kinds keep auto height. const fillHost = - this.visibleContent?.kind === "file" || this.visibleContent?.kind === "markdown"; + this.visibleContent?.kind === "file" || + this.visibleContent?.kind === "markdown" || + this.visibleContent?.kind === "session-diff"; return html`
= T extends unknown ? Omit : never; +export type SessionDiffMenuDraft = WithoutMenuAnchor; + +export type SessionDiffMenuAction = + | { kind: "collapse-all" } + | { kind: "copy-path"; path: string } + | { kind: "expand-all" } + | { kind: "open-editor"; editor: EditorId; path: string } + | { kind: "open-file"; path: string } + | { kind: "reveal-file"; path: string } + | { kind: "scope"; value: SessionDiffScope } + | { kind: "toggle-split" } + | { kind: "toggle-wrap" }; + +class SessionDiffMenu extends OpenClawLightDomElement { + @property({ attribute: false }) menu: SessionDiffMenuData | null = null; + @property({ attribute: false }) onAction: (action: SessionDiffMenuAction) => void = () => {}; + @property({ attribute: false }) onClose: () => void = () => {}; + + readonly menuLifecycle = new DropdownMenuController(this, { + getTrigger: () => this.menu?.trigger ?? null, + onClose: () => this.onClose(), + }); + + override connectedCallback() { + super.connectedCallback(); + promoteToPopoverTopLayer(this); + } + + private run(action: SessionDiffMenuAction) { + this.onClose(); + this.onAction(action); + } + + private readonly handleSelect = (event: CustomEvent<{ item: { value?: string } }>) => { + event.preventDefault(); + const value = event.detail.item.value; + if (!value) { + return; + } + const simple: Record = { + "collapse-all": { kind: "collapse-all" }, + "expand-all": { kind: "expand-all" }, + "toggle-split": { kind: "toggle-split" }, + "toggle-wrap": { kind: "toggle-wrap" }, + "scope:all": { kind: "scope", value: { scope: "all" } }, + "scope:uncommitted": { kind: "scope", value: { scope: "uncommitted" } }, + }; + const fileMenu = this.menu?.kind === "file" ? this.menu : null; + if (fileMenu && value === "copy-path") { + this.run({ kind: "copy-path", path: fileMenu.path }); + return; + } + if (fileMenu && value === "open-file") { + this.run({ kind: "open-file", path: fileMenu.path }); + return; + } + if (fileMenu && value === "reveal-file") { + this.run({ kind: "reveal-file", path: fileMenu.path }); + return; + } + const action = simple[value]; + if (action) { + this.run(action); + return; + } + if (value.startsWith("open-editor:")) { + const editor = value.slice("open-editor:".length) as EditorId; + if (EDITOR_IDS.includes(editor)) { + const path = this.menu?.kind === "file" ? this.menu.absolutePath : undefined; + if (path) { + this.run({ kind: "open-editor", editor, path }); + } + } + return; + } + if (value.startsWith("scope:commit:")) { + this.run({ + kind: "scope", + value: { scope: "commit", commit: value.slice("scope:commit:".length) }, + }); + } + }; + + private readonly handleAfterHide = (event: Event) => { + if (event.currentTarget instanceof Node && event.currentTarget.isConnected) { + this.onClose(); + } + }; + + private renderFileMenu(menu: Extract) { + return html` + + + ${t("chat.sessionDiff.copyPath")} + + + + ${t("chat.sessionDiff.openFile")} + + ${menu.canReveal + ? html` + + ${t("chat.sessionDiff.revealInFileTree")} + ` + : nothing} + ${menu.absolutePath + ? html` + + ${t("chat.sessionDiff.openInEditor")} + ${EDITOR_IDS.map( + (editor) => html` + ${EDITOR_LABELS[editor]} + `, + )} + ` + : nothing} + `; + } + + private renderViewMenu(menu: Extract) { + return html` + + ${t("chat.sessionDiff.collapseAll")} + + + ${t("chat.sessionDiff.expandAll")} + + + + ${t( + menu.wrap ? "chat.sessionDiff.disableWrapping" : "chat.sessionDiff.enableWrapping", + )} + + + ${t( + menu.split ? "chat.sessionDiff.switchUnified" : "chat.sessionDiff.switchSplit", + )} + + `; + } + + private renderScopeMenu(menu: Extract) { + const activeCommit = menu.active.scope === "commit" ? menu.active.commit : null; + return html` + ${this.renderScopeItem( + "scope:all", + t("chat.sessionDiff.allChanges"), + menu.active.scope === "all", + )} + ${this.renderScopeItem( + "scope:uncommitted", + t("chat.sessionDiff.uncommitted"), + menu.active.scope === "uncommitted", + )} + ${menu.result.commits?.length + ? html` + ${menu.result.commits.map((commit, index) => + this.renderScopeItem( + `scope:commit:${commit.sha}`, + html`${commit.sha} + ${commit.subject} + ${index === 0 + ? html`${t("chat.sessionDiff.head")}` + : nothing}`, + activeCommit === commit.sha, + ), + )}` + : nothing} + ${menu.result.mergeBase + ? html` +
+ ${t("chat.sessionDiff.mergeBase")} + ${menu.result.mergeBase.sha} + ${menu.result.mergeBase.subject} +
` + : nothing} + `; + } + + private renderScopeItem(value: string, label: unknown, checked: boolean) { + return html` + ${label} + ${checked + ? html`` + : nothing} + `; + } + + private renderSyncMenu(menu: Extract) { + return html`
+ ${t("chat.sessionDiff.syncLocally")} +

${t("chat.sessionDiff.syncDescription")}

+ ${this.renderCopyRow(menu.command, t("chat.sessionDiff.copyCommand"), true)} + ${this.renderCopyRow(menu.root, t("chat.sessionDiff.checkoutPath"))} + ${this.renderCopyRow(menu.branch, t("chat.sessionDiff.branchName"))} +

${t("chat.sessionDiff.uncommittedStay")}

+
`; + } + + private renderCopyRow(value: string, label: string, command = false) { + return html`
+ ${label} + ${value} + ${renderCopyButton(value, label)} +
`; + } + + override render() { + const menu = this.menu; + if (!menu) { + return nothing; + } + const placement = menu.kind === "scope" ? "top-start" : "bottom-end"; + const width = menu.kind === "sync" ? 360 : menu.kind === "scope" ? 340 : 240; + const menuLabel = + menu.kind === "file" + ? t("chat.sessionDiff.fileActions", { path: menu.path }) + : menu.kind === "scope" + ? t("chat.sessionDiff.scopeMenu") + : menu.kind === "sync" + ? t("chat.sessionDiff.syncLocally") + : t("chat.sessionDiff.viewOptions"); + const clampedX = Math.max(8, Math.min(menu.anchor.x, window.innerWidth - 8)); + const clampedY = Math.max(8, Math.min(menu.anchor.y, window.innerHeight - 8)); + return html` + + ${menu.kind === "file" + ? this.renderFileMenu(menu) + : menu.kind === "scope" + ? this.renderScopeMenu(menu) + : menu.kind === "sync" + ? this.renderSyncMenu(menu) + : this.renderViewMenu(menu)} + `; + } +} + +if (!customElements.get("openclaw-session-diff-menu")) { + customElements.define("openclaw-session-diff-menu", SessionDiffMenu); +} + +declare global { + interface HTMLElementTagNameMap { + "openclaw-session-diff-menu": SessionDiffMenu; + } +} diff --git a/ui/src/pages/chat/components/session-diff-panel.test.ts b/ui/src/pages/chat/components/session-diff-panel.test.ts index 12c9be8857e9..08fd4a6e31be 100644 --- a/ui/src/pages/chat/components/session-diff-panel.test.ts +++ b/ui/src/pages/chat/components/session-diff-panel.test.ts @@ -44,6 +44,7 @@ describe("SessionDiffPanel", () => { document.body.append(panel); await vi.waitFor(() => expect(firstLoader).toHaveBeenCalledOnce()); + expect(firstLoader).toHaveBeenCalledWith({ scope: "all" }); panel.loader = secondLoader; await vi.waitFor(() => expect(secondLoader).toHaveBeenCalledOnce()); diff --git a/ui/src/pages/chat/components/session-diff-panel.ts b/ui/src/pages/chat/components/session-diff-panel.ts index f98a83c0ee4e..7db54f9d1ffd 100644 --- a/ui/src/pages/chat/components/session-diff-panel.ts +++ b/ui/src/pages/chat/components/session-diff-panel.ts @@ -1,8 +1,8 @@ +// Session diff panel: renders selectable branch, working-tree, and commit diffs. import { Task, TaskStatus } from "@lit/task"; -// Session diff panel: renders the sessions.diff RPC result (branch + -// working-tree changes per file) inside the chat detail sidebar. import { html, nothing, type TemplateResult } from "lit"; import { property, state } from "lit/decorators.js"; +import { keyed } from "lit/directives/keyed.js"; import type { SessionDiffFile, SessionsDiffResult, @@ -10,11 +10,26 @@ import type { import { icons } from "../../../components/icons.ts"; import "../../../components/tooltip.ts"; import { t } from "../../../i18n/index.ts"; +import { + pairSessionDiffLines, + type SessionSplitDiffRow, +} from "../../../lib/chat/session-diff-split.ts"; import { parseSessionDiffPatch, type ParsedFilePatch } from "../../../lib/chat/session-diff.ts"; +import { copyToClipboard } from "../../../lib/clipboard.ts"; +import { openEditor } from "../../../lib/editor-links.ts"; import { OpenClawLightDomElement } from "../../../lit/openclaw-element.ts"; +import { getSafeLocalStorage } from "../../../local-storage.ts"; import { renderDiffBlock, renderDiffStatChips } from "./chat-diff-render.ts"; +import type { + SessionDiffMenuAction, + SessionDiffMenuData, + SessionDiffMenuDraft, + SessionDiffScope, +} from "./session-diff-menus.ts"; +import "./session-diff-menus.ts"; +import { renderSessionSplitDiff } from "./session-diff-render.ts"; -export type SessionDiffLoader = () => Promise; +export type SessionDiffLoader = (params: SessionDiffScope) => Promise; type FileView = { file: SessionDiffFile; @@ -26,6 +41,29 @@ type SessionDiffTaskResult = { views: FileView[]; }; +type SessionDiffPreferences = { split: boolean; wrap: boolean }; +const PREFERENCES_KEY = "openclaw.control.sessionDiff.v1"; + +function loadPreferences(): SessionDiffPreferences { + try { + const parsed = JSON.parse(getSafeLocalStorage()?.getItem(PREFERENCES_KEY) ?? "null") as { + split?: unknown; + wrap?: unknown; + } | null; + return { split: parsed?.split === true, wrap: parsed?.wrap === true }; + } catch { + return { split: false, wrap: false }; + } +} + +function savePreferences(preferences: SessionDiffPreferences): void { + try { + getSafeLocalStorage()?.setItem(PREFERENCES_KEY, JSON.stringify(preferences)); + } catch { + // Preferences are opportunistic; restricted storage must not break the viewer. + } +} + function statusLabel(file: SessionDiffFile): string { switch (file.status) { case "added": @@ -39,18 +77,80 @@ function statusLabel(file: SessionDiffFile): string { } } +function statusLetter(file: SessionDiffFile): string { + return file.status === "added" + ? "A" + : file.status === "deleted" + ? "D" + : file.status === "renamed" + ? "R" + : "M"; +} + +function diffStat(file: Pick) { + const modified = Math.min(file.additions, file.deletions); + return { + added: file.additions - modified, + removed: file.deletions - modified, + modified, + }; +} + +function totalDiffStat(files: readonly SessionDiffFile[]) { + return files.reduce( + (total, file) => { + const stat = diffStat(file); + total.added += stat.added; + total.removed += stat.removed; + total.modified += stat.modified; + return total; + }, + { added: 0, removed: 0, modified: 0 }, + ); +} + +function splitPath(filePath: string): { directory: string; name: string } { + const normalized = filePath.replaceAll("\\", "/"); + const separator = normalized.lastIndexOf("/"); + return separator < 0 + ? { directory: "", name: normalized } + : { directory: normalized.slice(0, separator), name: normalized.slice(separator + 1) }; +} + +function absolutePath(root: string, filePath: string): string { + return `${root.replace(/[\\/]+$/, "")}/${filePath.replace(/^[\\/]+/, "")}`; +} + +function shellArgument(value: string): string { + return /^[A-Za-z0-9_./:@+-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`; +} + class SessionDiffPanel extends OpenClawLightDomElement { @property({ attribute: false }) loader: SessionDiffLoader | null = null; + @property({ attribute: false }) openFile: ((path: string) => void) | null = null; + @property({ attribute: false }) revealFile: ((path: string) => void) | null = null; @state() private collapsedPaths = new Set(); + @state() private menu: SessionDiffMenuData | null = null; + @state() private scope: SessionDiffScope = { scope: "all" }; + @state() private split = loadPreferences().split; + @state() private wrap = loadPreferences().wrap; + + private readonly splitCache = new WeakMap(); private readonly diffTask = new Task(this, { - args: () => [this.loader] as const, - task: async ([loader]): Promise => { + args: () => + [ + this.loader, + this.scope.scope, + this.scope.scope === "commit" ? this.scope.commit : null, + ] as const, + task: async ([loader, scope, commit]): Promise => { if (!loader) { return null; } - const result = await loader(); + const params: SessionDiffScope = scope === "commit" ? { scope, commit: commit! } : { scope }; + const result = await loader(params); return { result, views: result.files.map((file) => ({ @@ -63,8 +163,11 @@ class SessionDiffPanel extends OpenClawLightDomElement { })), }; }, - onComplete: () => { - this.collapsedPaths = new Set(); + onComplete: (value) => { + const currentPaths = new Set(value?.views.map((view) => view.file.path) ?? []); + this.collapsedPaths = new Set( + [...this.collapsedPaths].filter((path) => currentPaths.has(path)), + ); }, }); @@ -86,18 +189,102 @@ class SessionDiffPanel extends OpenClawLightDomElement { this.collapsedPaths = next; } + private openAnchoredMenu(event: Event, menu: SessionDiffMenuDraft, upward = false): void { + event.stopPropagation(); + const trigger = event.currentTarget; + if (!(trigger instanceof HTMLElement)) { + return; + } + const bounds = trigger.getBoundingClientRect(); + this.menu = { + ...menu, + anchor: { x: upward ? bounds.left : bounds.right, y: upward ? bounds.top : bounds.bottom }, + trigger, + } as SessionDiffMenuData; + } + + private handleMenuAction(action: SessionDiffMenuAction): void { + switch (action.kind) { + case "collapse-all": { + const views = this.diffTask.value?.views ?? []; + this.collapsedPaths = new Set(views.map((view) => view.file.path)); + return; + } + case "expand-all": + this.collapsedPaths = new Set(); + return; + case "toggle-wrap": + this.wrap = !this.wrap; + savePreferences({ split: this.split, wrap: this.wrap }); + return; + case "toggle-split": + this.split = !this.split; + savePreferences({ split: this.split, wrap: this.wrap }); + return; + case "scope": + this.scope = action.value; + return; + case "copy-path": + void copyToClipboard(action.path); + return; + case "open-file": + this.openFile?.(action.path); + return; + case "reveal-file": + this.revealFile?.(action.path); + return; + case "open-editor": + openEditor(action.editor, action.path); + } + } + private renderSummary(result: SessionsDiffResult): TemplateResult { const branchLabel = result.baseRef && result.branch && result.baseRef !== result.branch ? `${result.baseRef} → ${result.branch}` : (result.branch ?? result.baseRef ?? ""); + const syncCommand = + result.root && result.branch + ? `git fetch ${shellArgument(result.root)} ${shellArgument(result.branch)} && git checkout FETCH_HEAD` + : null; return html`
${icons.gitBranch} ${branchLabel} - ${renderDiffStatChips({ added: result.additions, removed: result.deletions })} + ${renderDiffStatChips(totalDiffStat(result.files))} + + ${syncCommand && result.root && result.branch + ? html`` + : nothing} + + +
`; } return html` - ${renderDiffBlock(parsed.lines)} + ${this.split ? renderSessionSplitDiff(this.splitRows(parsed)) : renderDiffBlock(parsed.lines)} ${parsed.truncated ? html`
${t("chat.sessionDiff.truncatedFile")}
` : nothing} `; } - private renderFile(view: FileView): TemplateResult { + private renderFile(view: FileView, result: SessionsDiffResult): TemplateResult { const { file } = view; const collapsed = this.collapsedPaths.has(file.path); + const { directory, name } = splitPath(file.path); + const absPath = result.root ? absolutePath(result.root, file.path) : undefined; + const pathTitle = file.oldPath ? `${file.oldPath} → ${file.path}` : file.path; return html`
- - ${collapsed ? nothing : this.renderFileBody(view)} +
+ + +
+ ${collapsed + ? nothing + : html`
+ ${this.renderFileBody(view)} +
`}
`; } + private scopeTitle(result: SessionsDiffResult): string { + const scope = this.scope; + if (scope.scope === "uncommitted") { + return t("chat.sessionDiff.uncommitted"); + } + if (scope.scope === "commit") { + const commit = result.commits?.find((entry) => entry.sha === scope.commit); + return commit ? `${commit.sha} ${commit.subject}` : scope.commit; + } + return t("chat.sessionDiff.allChanges"); + } + + private renderFooter(result: SessionsDiffResult): TemplateResult { + const branchLabel = result.branch ?? result.baseRef ?? t("chat.sessionDiff.allChanges"); + const label = + result.aheadCount && result.baseRef + ? t("chat.sessionDiff.commitsAhead", { + count: String(result.aheadCount), + base: result.baseRef, + }) + : branchLabel; + return html``; + } + private renderBody(): TemplateResult { if (this.diffTask.status === TaskStatus.ERROR) { const error = this.diffTask.error; @@ -182,18 +447,41 @@ class SessionDiffPanel extends OpenClawLightDomElement { } return html` ${this.renderSummary(result)} - ${result.files.length === 0 - ? html`
${t("chat.sessionDiff.empty")}
` - : views.map((view) => this.renderFile(view))} - ${result.truncated === true - ? html`
${t("chat.sessionDiff.truncatedResult")}
` - : nothing} +
${this.scopeTitle(result)}
+
+ ${result.unavailableReason === "unknown_commit" + ? html`
${t("chat.sessionDiff.unknownCommit")}
` + : result.files.length === 0 + ? html`
${t("chat.sessionDiff.empty")}
` + : views.map((view) => this.renderFile(view, result))} + ${result.truncated === true + ? html`
${t("chat.sessionDiff.truncatedResult")}
` + : nothing} +
+ ${this.renderFooter(result)} `; } override render() { return html` -
${this.renderBody()}
+
+ ${this.renderBody()} + ${this.menu + ? keyed( + this.menu, + html` this.handleMenuAction(action)} + .onClose=${() => { + this.menu = null; + }} + >`, + ) + : nothing} +
`; } } diff --git a/ui/src/pages/chat/components/session-diff-render.ts b/ui/src/pages/chat/components/session-diff-render.ts new file mode 100644 index 000000000000..bbcc8580dbfa --- /dev/null +++ b/ui/src/pages/chat/components/session-diff-render.ts @@ -0,0 +1,44 @@ +import { html } from "lit"; +import { t } from "../../../i18n/index.ts"; +import type { SessionSplitDiffRow } from "../../../lib/chat/session-diff-split.ts"; +import type { DiffLine } from "../../../lib/chat/tool-call-diff.ts"; + +function renderSplitSide(line: DiffLine | undefined, side: "left" | "right") { + const sign = side === "left" ? "-" : "+"; + // Tint only sides that carry a line; a lone add/del keeps its counterpart neutral. + return html`
+ ${line?.lineNo ?? ""} + ${line ? sign : ""} + ${line?.text || (line ? " " : "")} +
`; +} + +export function renderSessionSplitDiff(rows: readonly SessionSplitDiffRow[]) { + return html`
+ ${rows.map((row) => { + if (row.kind === "pair") { + return html`
+ ${renderSplitSide(row.left, "left")} ${renderSplitSide(row.right, "right")} +
`; + } + if (row.line.kind === "skip") { + return html`
+ ${row.line.text || "⋯"} +
`; + } + return html`
+ ${row.line.lineNo ?? ""} + + ${row.line.text || " "} +
`; + })} +
`; +} diff --git a/ui/src/styles/chat/sidebar.css b/ui/src/styles/chat/sidebar.css index d5ca757dcf1f..77d1b203d301 100644 --- a/ui/src/styles/chat/sidebar.css +++ b/ui/src/styles/chat/sidebar.css @@ -1923,15 +1923,24 @@ openclaw-session-discussion { .session-diff { display: flex; + min-height: 100%; flex-direction: column; - gap: 10px; + gap: 0; + margin: -8px; + font-size: var(--control-ui-text-sm); } .session-diff__summary { + position: sticky; + top: -16px; + z-index: 3; display: flex; align-items: center; - gap: 8px; - padding-bottom: 2px; + gap: 6px; + min-height: 38px; + padding: 4px 8px; + border-bottom: 1px solid color-mix(in srgb, var(--border) 72%, transparent); + background: var(--panel); } .session-diff__branch { @@ -1939,7 +1948,7 @@ openclaw-session-discussion { align-items: center; gap: 6px; min-width: 0; - font-weight: 600; + font-weight: 550; font-size: var(--control-ui-text-sm); } @@ -1951,30 +1960,83 @@ openclaw-session-discussion { } .session-diff__branch-label { + max-width: 170px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: var(--mono); } +.session-diff__summary-spacer { + flex: 1; +} + +.session-diff__toolbar-button, +.session-diff__toolbar-icon, .session-diff__refresh { - margin-left: auto; + min-width: 26px; + height: 26px; + min-height: 26px; + padding: 4px; +} + +.session-diff__toolbar-button { + display: inline-flex; + align-items: center; + gap: 2px; + padding-inline: 7px; +} + +.session-diff__toolbar-button svg, +.session-diff__toolbar-icon svg, +.session-diff__refresh svg { + width: 14px; + height: 14px; +} + +.session-diff__section-title { + padding: 11px 8px 6px; + color: var(--muted); + font-size: var(--control-ui-text-xs); + font-weight: 650; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.session-diff__files { + display: flex; + flex-direction: column; + gap: 2px; + padding-bottom: 8px; } .session-diff__file { - border: 1px solid color-mix(in srgb, var(--border) 80%, transparent); - border-radius: var(--radius-sm); + border-block: 1px solid transparent; overflow: hidden; } +.session-diff__file:focus-within, +.session-diff__file:hover { + border-color: color-mix(in srgb, var(--border) 68%, transparent); + background: color-mix(in srgb, var(--secondary) 42%, transparent); +} + .session-diff__file-header { display: flex; align-items: center; - gap: 8px; width: 100%; - padding: 6px 10px; - border: 0; - background: color-mix(in srgb, var(--secondary) 70%, transparent); + min-height: 34px; +} + +.session-diff__file-toggle { + display: flex; + align-items: center; + gap: 7px; + min-width: 0; + flex: 1; + padding: 6px 4px 6px 8px; + border: none; + background: transparent; color: var(--text); font: inherit; font-size: var(--control-ui-text-sm); @@ -1982,6 +2044,11 @@ openclaw-session-discussion { cursor: var(--cursor-action); } +.session-diff__file-toggle:focus-visible { + outline: 1px solid var(--accent); + outline-offset: -1px; +} + .session-diff__chevron { display: inline-flex; flex-shrink: 0; @@ -1999,38 +2066,71 @@ openclaw-session-discussion { } .session-diff__status { + display: inline-flex; + align-items: center; + justify-content: center; flex-shrink: 0; - width: 8px; - height: 8px; - border-radius: 50%; - background: var(--muted); + width: 18px; + height: 18px; + border: 1px solid color-mix(in srgb, currentColor 35%, transparent); + border-radius: 4px; + background: color-mix(in srgb, currentColor 10%, transparent); + color: var(--muted); + font-family: var(--mono); + font-size: 10px; + font-weight: 700; } .session-diff__status--added { - background: var(--ok); + color: var(--ok); } .session-diff__status--deleted { - background: var(--destructive); + color: var(--destructive); } .session-diff__status--renamed { - background: var(--accent); + color: var(--accent); } .session-diff__status--modified { - background: var(--warn); + color: var(--warn); } .session-diff__path { + display: flex; + align-items: baseline; + gap: 6px; flex: 1; min-width: 0; - overflow-wrap: anywhere; font-family: var(--mono); + white-space: nowrap; } .session-diff__old-path { + overflow: hidden; + max-width: 110px; + flex-shrink: 1; + text-overflow: ellipsis; color: var(--muted); + font-size: var(--control-ui-text-xs); +} + +.session-diff__filename { + overflow: hidden; + flex-shrink: 0; + max-width: 48%; + text-overflow: ellipsis; + color: var(--text-strong); + font-weight: 550; +} + +.session-diff__directory { + overflow: hidden; + min-width: 0; + text-overflow: ellipsis; + color: var(--muted); + font-size: var(--control-ui-text-xs); } .session-diff__badge { @@ -2042,14 +2142,276 @@ openclaw-session-discussion { font-size: calc(var(--control-ui-text-sm) - 2px); } +.session-diff .chat-diffstat { + gap: 5px; + font-size: var(--control-ui-text-xs); +} + +.session-diff .chat-diffstat__mod { + color: var(--warn); +} + +.session-diff__file-menu { + width: 26px; + min-width: 26px; + height: 26px; + min-height: 26px; + margin-right: 4px; + padding: 4px; + opacity: 0; +} + +.session-diff__file:focus-within .session-diff__file-menu, +.session-diff__file:hover .session-diff__file-menu { + opacity: 1; +} + +.session-diff__file-menu svg { + width: 14px; + height: 14px; +} + +.session-diff__file-body { + content-visibility: auto; +} + .session-diff__file .chat-diff { margin-top: 0; border-radius: 0; max-height: none; + border-top: 1px solid color-mix(in srgb, var(--border) 55%, transparent); + background: color-mix(in srgb, var(--secondary) 45%, transparent); + line-height: 1.45; +} + +.session-diff__file .chat-diff__row { + padding-right: 8px; +} + +.session-diff--wrap .chat-diff__row { + min-width: 0; +} + +.session-diff--wrap .chat-diff__text, +.session-diff--wrap .session-diff-split__text { + min-width: 0; + white-space: pre-wrap; + overflow-wrap: anywhere; } .session-diff__note { - padding: 2px 2px 4px; + padding: 10px; color: var(--muted); font-size: var(--control-ui-text-sm); } + +.session-diff__footer { + position: sticky; + bottom: -16px; + z-index: 3; + display: flex; + align-items: center; + justify-content: space-between; + width: 100%; + min-height: 36px; + margin-top: auto; + padding: 7px 10px; + border: 0; + border-top: 1px solid color-mix(in srgb, var(--border) 72%, transparent); + background: var(--panel); + color: var(--muted); + font: inherit; + font-size: var(--control-ui-text-xs); + text-align: left; + cursor: var(--cursor-action); +} + +.session-diff__footer:hover, +.session-diff__footer:focus-visible { + background: color-mix(in srgb, var(--secondary) 62%, var(--panel)); + color: var(--text); +} + +.session-diff__footer svg { + width: 14px; + height: 14px; +} + +.session-diff-split { + overflow: auto; + border-top: 1px solid color-mix(in srgb, var(--border) 55%, transparent); + background: color-mix(in srgb, var(--secondary) 45%, transparent); + font-family: var(--mono); + font-size: 12px; + line-height: 1.45; +} + +.session-diff-split__row--pair { + display: grid; + grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); + min-width: 640px; +} + +.session-diff-split__side, +.session-diff-split__row--context { + display: grid; + grid-template-columns: 42px 16px minmax(max-content, 1fr); + align-items: baseline; + min-width: 0; +} + +.session-diff-split__side--left { + border-right: 1px solid color-mix(in srgb, var(--border) 55%, transparent); +} + +.session-diff-split__side--left.session-diff-split__side--filled { + background: color-mix(in srgb, var(--destructive) 12%, transparent); +} + +.session-diff-split__side--right.session-diff-split__side--filled { + background: color-mix(in srgb, var(--ok) 13%, transparent); +} + +.session-diff-split__row--context { + min-width: max-content; +} + +.session-diff-split__row--skip { + padding-left: 58px; + color: var(--muted); + user-select: none; +} + +.session-diff-split__gutter { + padding-right: 8px; + text-align: right; + color: color-mix(in srgb, var(--muted) 75%, transparent); + user-select: none; +} + +.session-diff-split__sign { + text-align: center; + font-weight: 600; + user-select: none; +} + +.session-diff-split__side--left .session-diff-split__sign { + color: var(--destructive); +} + +.session-diff-split__side--right .session-diff-split__sign { + color: var(--ok); +} + +.session-diff-split__text { + padding-right: 8px; + color: var(--text); + white-space: pre; + tab-size: 4; +} + +openclaw-session-diff-menu[popover] { + width: 0; + height: 0; + margin: 0; + padding: 0; + overflow: visible; + border: 0; + background: transparent; +} + +wa-dropdown.session-diff-menu::part(menu) { + width: min(var(--session-diff-menu-width), calc(100vw - 16px)); + min-width: min(var(--session-diff-menu-width), calc(100vw - 16px)); + max-width: min(var(--session-diff-menu-width), calc(100vw - 16px)); +} + +.session-diff-menu__scope-item .session-menu__text { + display: flex; + align-items: baseline; + gap: 7px; + min-width: 0; +} + +.session-diff-menu__sha { + flex: 0 0 auto; + color: var(--muted); + font-family: var(--mono); + font-size: var(--control-ui-text-xs); +} + +.session-diff-menu__subject { + overflow: hidden; + min-width: 0; + text-overflow: ellipsis; + white-space: nowrap; +} + +.session-diff-menu__head { + flex: 0 0 auto; + padding: 0 4px; + border-radius: 3px; + background: color-mix(in srgb, var(--accent) 15%, transparent); + color: var(--accent); + font-size: 9px; + font-weight: 700; +} + +.session-diff-menu__merge-base { + display: grid; + grid-template-columns: auto auto minmax(0, 1fr); + gap: 7px; + padding: 6px 8px; + color: var(--muted); + font-size: var(--control-ui-text-xs); +} + +.session-diff-menu__sync { + display: flex; + flex-direction: column; + gap: 8px; + padding: 8px; +} + +.session-diff-menu__sync p { + margin: 0; + color: var(--muted); + font-size: var(--control-ui-text-xs); + line-height: 1.4; +} + +.session-diff-menu__copy-row { + display: grid; + grid-template-columns: minmax(0, 1fr) auto; + align-items: center; + gap: 6px; +} + +.session-diff-menu__copy-label { + grid-column: 1 / -1; + color: var(--muted); + font-size: var(--control-ui-text-xs); +} + +.session-diff-menu__copy-row code { + overflow: hidden; + padding: 4px 6px; + border-radius: var(--radius-sm); + background: color-mix(in srgb, var(--secondary) 70%, transparent); + color: var(--text); + font-size: var(--control-ui-text-xs); + text-overflow: ellipsis; + white-space: nowrap; +} + +.session-diff-menu__copy-row.is-command code { + white-space: normal; + overflow-wrap: anywhere; +} + +.session-diff-menu__copy-row .chat-copy-btn { + width: 28px; + min-width: 28px; + height: 28px; + padding: 5px; +} From 83649466fa1699701809a75d3eb8e7bc1f3c0338 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 12 Aug 2026 16:08:43 +0800 Subject: [PATCH 067/165] fix(qa): isolate gateway child skip controls (#122534) --- extensions/qa-lab/src/gateway-child.test.ts | 28 +++++++++++++++++++++ extensions/qa-lab/src/gateway-child.ts | 3 +++ 2 files changed, 31 insertions(+) diff --git a/extensions/qa-lab/src/gateway-child.test.ts b/extensions/qa-lab/src/gateway-child.test.ts index 71cc5c68a7aa..cae7bbcdba8e 100644 --- a/extensions/qa-lab/src/gateway-child.test.ts +++ b/extensions/qa-lab/src/gateway-child.test.ts @@ -636,6 +636,34 @@ describe("buildQaRuntimeEnv", () => { expect(developmentEnv.NODE_ENV).toBe("development"); }); + it("does not inherit parent channel or provider skip controls", () => { + const env = buildQaRuntimeEnv({ + ...createParams({ + OPENCLAW_SKIP_CHANNELS: "1", + OPENCLAW_SKIP_PROVIDERS: "1", + }), + }); + + expect(env.OPENCLAW_SKIP_CHANNELS).toBeUndefined(); + expect(env.OPENCLAW_SKIP_PROVIDERS).toBeUndefined(); + }); + + it("honors explicit channel and provider skip controls", () => { + const env = buildQaRuntimeEnv({ + ...createParams({ + OPENCLAW_SKIP_CHANNELS: "inherited", + OPENCLAW_SKIP_PROVIDERS: "inherited", + }), + runtimeEnvPatch: { + OPENCLAW_SKIP_CHANNELS: "patched-channels", + OPENCLAW_SKIP_PROVIDERS: "patched-providers", + }, + }); + + expect(env.OPENCLAW_SKIP_CHANNELS).toBe("patched-channels"); + expect(env.OPENCLAW_SKIP_PROVIDERS).toBe("patched-providers"); + }); + it("maps live frontier key aliases into provider env vars", () => { const env = buildQaRuntimeEnv({ ...createParams({ diff --git a/extensions/qa-lab/src/gateway-child.ts b/extensions/qa-lab/src/gateway-child.ts index 7250dace25e5..4b9f2fe6f166 100644 --- a/extensions/qa-lab/src/gateway-child.ts +++ b/extensions/qa-lab/src/gateway-child.ts @@ -543,6 +543,9 @@ export function buildQaRuntimeEnv(params: { : {}), }; const normalizedEnv = normalizeQaProviderModeEnv(env, params.providerMode); + // Test-runner skip flags are parent controls; each QA child declares its own runtime needs. + delete normalizedEnv.OPENCLAW_SKIP_CHANNELS; + delete normalizedEnv.OPENCLAW_SKIP_PROVIDERS; Object.assign(normalizedEnv, params.runtimeEnvPatch); normalizedEnv.OPENCLAW_BUILD_PRIVATE_QA = "1"; delete normalizedEnv[QA_LIVE_ANTHROPIC_SETUP_TOKEN_ENV]; From dfbdbf2a67def12ecb45187dab30f91dac13e73f Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 12 Aug 2026 16:16:22 +0800 Subject: [PATCH 068/165] fix(provider-runtime): retry transient socket failures (#122535) * test: cover UND_ERR_SOCKET retry recovery Punchcard-Session: golden-cedar-brook-4q * fix(provider-runtime): retry UND_ERR_SOCKET failures Punchcard-Session: golden-cedar-brook-4q --- src/agents/run-wait.test.ts | 1 + src/infra/retryable-network-errors.ts | 2 +- src/provider-runtime/operation-retry.test.ts | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/agents/run-wait.test.ts b/src/agents/run-wait.test.ts index 344063256018..3385701f690f 100644 --- a/src/agents/run-wait.test.ts +++ b/src/agents/run-wait.test.ts @@ -838,6 +838,7 @@ describe("isRecoverableAgentWaitError", () => { "EHOSTUNREACH", "ENETUNREACH", "EAI_AGAIN", + "UND_ERR_SOCKET", ])("recovers from %s connection failures", (code) => { expect(isRecoverableAgentWaitError(`connect ${code} 127.0.0.1:443`)).toBe(true); }); diff --git a/src/infra/retryable-network-errors.ts b/src/infra/retryable-network-errors.ts index f048fab9bb9f..e619adbe22d2 100644 --- a/src/infra/retryable-network-errors.ts +++ b/src/infra/retryable-network-errors.ts @@ -55,7 +55,7 @@ const TRANSIENT_NETWORK_MESSAGE_SNIPPETS = [ ]; const RETRYABLE_CONNECTION_ERROR_CODE_RE = - /\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN)\b/i; + /\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN|UND_ERR_SOCKET)\b/i; function isWrappedFetchFailedMessage(message: string): boolean { if (message === "fetch failed") { diff --git a/src/provider-runtime/operation-retry.test.ts b/src/provider-runtime/operation-retry.test.ts index 3e12125f14cf..42ab8e9602ab 100644 --- a/src/provider-runtime/operation-retry.test.ts +++ b/src/provider-runtime/operation-retry.test.ts @@ -51,6 +51,7 @@ describe("executeProviderOperationWithRetry", () => { "EHOSTUNREACH", "ENETUNREACH", "EAI_AGAIN", + "UND_ERR_SOCKET", "ENOTFOUND", ])("retries %s network failures from structured errors", async (code) => { const cause = Object.assign(new Error("connect failed"), { code }); From 08142099dad910128d40bcc529c3ea1d6f972d3e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:20:09 -0700 Subject: [PATCH 069/165] refactor(plugins): remove test-only facades and adapter (#122532) * refactor(plugins): trim test-only facades * refactor(whatsapp): remove legacy outbound adapter --- extensions/active-memory/index.ts | 2 +- extensions/discord/runtime-api.threads.ts | 1 - extensions/discord/runtime-api.ts | 2 - .../src/monitor/thread-bindings.manager.ts | 1 - extensions/feishu/api.ts | 3 - extensions/imessage/api.ts | 6 +- extensions/qa-lab/api.ts | 2 - extensions/qa-lab/src/cli.runtime.ts | 4 - extensions/slack/outbound-payload-test-api.ts | 2 - .../whatsapp/outbound-payload-test-api.ts | 2 - .../src/auto-reply/deliver-reply.test.ts | 74 ------ .../whatsapp/src/channel-outbound.test.ts | 71 +++++- .../src/outbound-adapter.poll.test.ts | 63 ----- .../src/outbound-adapter.sendpayload.test.ts | 214 ----------------- extensions/whatsapp/src/outbound-adapter.ts | 31 --- .../src/outbound-payload.contract.test.ts | 217 ------------------ .../plugin-sdk-runtime-api-guardrails.test.ts | 2 +- 17 files changed, 73 insertions(+), 624 deletions(-) delete mode 100644 extensions/slack/outbound-payload-test-api.ts delete mode 100644 extensions/whatsapp/outbound-payload-test-api.ts delete mode 100644 extensions/whatsapp/src/outbound-adapter.poll.test.ts delete mode 100644 extensions/whatsapp/src/outbound-adapter.sendpayload.test.ts delete mode 100644 extensions/whatsapp/src/outbound-adapter.ts delete mode 100644 extensions/whatsapp/src/outbound-payload.contract.test.ts diff --git a/extensions/active-memory/index.ts b/extensions/active-memory/index.ts index d769bf7588d0..71c79405c94f 100644 --- a/extensions/active-memory/index.ts +++ b/extensions/active-memory/index.ts @@ -589,4 +589,4 @@ const testing = { getCircuitBreakerEntry, }; -export { testing, testing as __testing }; +export { testing }; diff --git a/extensions/discord/runtime-api.threads.ts b/extensions/discord/runtime-api.threads.ts index 83f09578ce61..95ee417071d0 100644 --- a/extensions/discord/runtime-api.threads.ts +++ b/extensions/discord/runtime-api.threads.ts @@ -1,6 +1,5 @@ // Discord plugin module implements runtime api.threads behavior. export { - testing, autoBindSpawnedDiscordSubagent, createNoopThreadBindingManager, createThreadBindingManager, diff --git a/extensions/discord/runtime-api.ts b/extensions/discord/runtime-api.ts index c51aeb0c5757..f1e18ebd1a84 100644 --- a/extensions/discord/runtime-api.ts +++ b/extensions/discord/runtime-api.ts @@ -152,8 +152,6 @@ export { type ResolveDiscordOutboundSessionRouteParams, } from "./runtime-api.send.js"; export { - testing as __testing, - testing, autoBindSpawnedDiscordSubagent, createNoopThreadBindingManager, createThreadBindingManager, diff --git a/extensions/discord/src/monitor/thread-bindings.manager.ts b/extensions/discord/src/monitor/thread-bindings.manager.ts index 33e435c6cbd6..5c6f48baee4f 100644 --- a/extensions/discord/src/monitor/thread-bindings.manager.ts +++ b/extensions/discord/src/monitor/thread-bindings.manager.ts @@ -554,4 +554,3 @@ export const testing = { } }, }; -export { testing as __testing }; diff --git a/extensions/feishu/api.ts b/extensions/feishu/api.ts index 438d8eeb45a1..a9a35fe7173f 100644 --- a/extensions/feishu/api.ts +++ b/extensions/feishu/api.ts @@ -22,10 +22,7 @@ export { export { feishuSetupAdapter, setFeishuNamedAccountEnabled } from "./src/setup-core.js"; export { feishuSetupWizard, runFeishuLogin } from "./src/setup-surface.js"; export { - testing as __testing, - testing, createFeishuThreadBindingManager, getFeishuThreadBindingManager, } from "./src/thread-bindings.js"; -export { testing as feishuThreadBindingTesting } from "./src/thread-bindings.js"; export { createClackPrompter } from "openclaw/plugin-sdk/setup-runtime"; diff --git a/extensions/imessage/api.ts b/extensions/imessage/api.ts index 35454579f6b1..e438dfae13b5 100644 --- a/extensions/imessage/api.ts +++ b/extensions/imessage/api.ts @@ -8,11 +8,7 @@ export { type ResolvedIMessageAccount, resolveIMessageAccount, } from "./src/accounts.js"; -export { - testing, - testing as __testing, - createIMessageConversationBindingManager, -} from "./src/conversation-bindings.js"; +export { createIMessageConversationBindingManager } from "./src/conversation-bindings.js"; export { matchIMessageAcpConversation, normalizeIMessageAcpConversationId, diff --git a/extensions/qa-lab/api.ts b/extensions/qa-lab/api.ts index 40de59d2be6d..eed290c13f9b 100644 --- a/extensions/qa-lab/api.ts +++ b/extensions/qa-lab/api.ts @@ -24,7 +24,6 @@ export { DEFAULT_WAIT_TIMEOUT_MS, type QaBusWaitMatch, } from "./src/bus-waiters.js"; -export { isQaLabCliAvailable, registerQaLabCli } from "./src/cli.js"; export { createQaRunnerRuntime } from "./src/harness-runtime.js"; export { buildScriptEvidenceSummary, @@ -101,7 +100,6 @@ export { export { runQaE2eSelfCheck, runQaLabSelfCheck } from "./src/self-check-runner.js"; export { testing, - testing as __testing, buildQaRuntimeEnv, type QaCliBackendAuthMode, type QaGatewayChildListeningContext, diff --git a/extensions/qa-lab/src/cli.runtime.ts b/extensions/qa-lab/src/cli.runtime.ts index 7d5ade04925b..33f29bbbe06c 100644 --- a/extensions/qa-lab/src/cli.runtime.ts +++ b/extensions/qa-lab/src/cli.runtime.ts @@ -1736,8 +1736,4 @@ export async function runQaProviderServerCommand( await runInterruptibleServer(standaloneCommand.serverLabel, server); } -export const testing = { - resolveRepoRelativeOutputDir, -}; -export { testing as __testing }; /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/extensions/slack/outbound-payload-test-api.ts b/extensions/slack/outbound-payload-test-api.ts deleted file mode 100644 index ed65ed6a78a0..000000000000 --- a/extensions/slack/outbound-payload-test-api.ts +++ /dev/null @@ -1,2 +0,0 @@ -// Slack API module exposes the plugin public contract. -export { createSlackOutboundPayloadHarness } from "./src/outbound-payload.test-harness.js"; diff --git a/extensions/whatsapp/outbound-payload-test-api.ts b/extensions/whatsapp/outbound-payload-test-api.ts deleted file mode 100644 index 76d4f09d858f..000000000000 --- a/extensions/whatsapp/outbound-payload-test-api.ts +++ /dev/null @@ -1,2 +0,0 @@ -// Whatsapp API module exposes the plugin public contract. -export { whatsappOutbound } from "./src/outbound-adapter.js"; diff --git a/extensions/whatsapp/src/auto-reply/deliver-reply.test.ts b/extensions/whatsapp/src/auto-reply/deliver-reply.test.ts index 9055d00d2caf..cf5767193a44 100644 --- a/extensions/whatsapp/src/auto-reply/deliver-reply.test.ts +++ b/extensions/whatsapp/src/auto-reply/deliver-reply.test.ts @@ -59,7 +59,6 @@ vi.mock("../media.js", () => ({ loadWebMedia: vi.fn() })); let deliverWebReply: typeof import("./deliver-reply.js").deliverWebReply; let createWhatsAppReplyTransportContext: typeof import("./deliver-reply.js").createWhatsAppReplyTransportContext; -let whatsappOutbound: typeof import("../outbound-adapter.js").whatsappOutbound; type DeliveryParams = Parameters[0]; type DeliveryOverrides = Partial>; @@ -220,7 +219,6 @@ async function expectReplySuppressed(replyResult: { text: string; isReasoning?: describe("deliverWebReply", () => { beforeAll(async () => { ({ createWhatsAppReplyTransportContext, deliverWebReply } = await import("./deliver-reply.js")); - ({ whatsappOutbound } = await import("../outbound-adapter.js")); }); it("does not resend an accepted reply when its transport reports a disconnect afterward", async () => { @@ -737,78 +735,6 @@ describe("deliverWebReply", () => { ); }); - it("sanitizes XML tool-call blocks for outbound sendPayload delivery", async () => { - const sendWhatsApp = vi.fn(async (_to: string, _text: string) => ({ - messageId: "wa-1", - toJid: "jid", - })); - - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { - text: 'Before\nx\nAfter', - }, - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenCalledTimes(1); - const sentText = mockCallArg(sendWhatsApp, 0, 1, "sendWhatsApp"); - expect(sentText).not.toContain("function_calls"); - expect(sentText).not.toContain("invoke"); - expect(sentText).toContain("Before"); - expect(sentText).toContain("After"); - }); - - it("keeps payload and auto-reply media normalization in parity", async () => { - const payload = { - text: "\n\ncaption", - mediaUrls: [" ", " /tmp/voice.ogg "], - }; - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload, - deps: { sendWhatsApp }, - }); - - const { msg, params } = createDelivery(payload); - mockLoadedMedia("aud", "audio/ogg", "audio"); - - await deliverWebReply(params); - - expect(sendWhatsApp).toHaveBeenCalledTimes(1); - expect(sendWhatsApp).toHaveBeenCalledWith( - "5511999999999@c.us", - "caption", - expect.objectContaining({ - verbose: false, - cfg: {}, - mediaUrl: "/tmp/voice.ogg", - mediaLocalRoots: undefined, - accountId: undefined, - gifPlayback: undefined, - onDeliveryResult: expect.any(Function), - }), - ); - expect(loadWebMedia).toHaveBeenCalledWith("/tmp/voice.ogg", { - maxBytes: 1024 * 1024, - localRoots: undefined, - }); - expect(msg.platform.sendMedia).toHaveBeenCalledTimes(1); - const mediaPayload = expectFirstSendMediaPayload(msg); - expectBuffer(mediaPayload.audio, "sendMedia audio"); - expect(mediaPayload.ptt).toBe(true); - expect(mediaPayload.mimetype).toBe("audio/ogg; codecs=opus"); - expect(mockCallArg(msg.platform.sendMedia, 0, 1, "sendMedia")).toBeUndefined(); - expect(expectFirstSendMediaPayload(msg)).not.toHaveProperty("caption"); - expect(msg.platform.reply).toHaveBeenCalledWith("caption", undefined); - }); - it("sends audio media as ptt voice note with visible text separately", async () => { const { msg, params } = createDelivery({ text: "cap", diff --git a/extensions/whatsapp/src/channel-outbound.test.ts b/extensions/whatsapp/src/channel-outbound.test.ts index 6b29899f8712..4a1c1f901a8e 100644 --- a/extensions/whatsapp/src/channel-outbound.test.ts +++ b/extensions/whatsapp/src/channel-outbound.test.ts @@ -3,6 +3,7 @@ import type { ExecApprovalRequest, PluginApprovalRequest, } from "openclaw/plugin-sdk/approval-runtime"; +import { verifyChannelMessageAdapterCapabilityProofs } from "openclaw/plugin-sdk/channel-outbound"; import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; import type { MessagePresentationAction } from "openclaw/plugin-sdk/interactive-runtime"; import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; @@ -29,6 +30,7 @@ vi.mock("./runtime.js", () => ({ })); let whatsappChannelOutbound: typeof import("./channel-outbound.js").whatsappChannelOutbound; +let whatsappMessageAdapter: typeof import("./channel-outbound.js").whatsappMessageAdapter; let clearWhatsAppApprovalReactionTargetsForTest: typeof import("./approval-reactions.js").clearWhatsAppApprovalReactionTargetsForTest; let resolveWhatsAppApprovalReactionTargetWithPersistence: typeof import("./approval-reactions.js").resolveWhatsAppApprovalReactionTargetWithPersistence; @@ -36,7 +38,7 @@ type ApprovalAction = Extract; describe("whatsappChannelOutbound", () => { beforeAll(async () => { - ({ whatsappChannelOutbound } = await import("./channel-outbound.js")); + ({ whatsappChannelOutbound, whatsappMessageAdapter } = await import("./channel-outbound.js")); ({ clearWhatsAppApprovalReactionTargetsForTest, resolveWhatsAppApprovalReactionTargetWithPersistence, @@ -534,4 +536,71 @@ describe("whatsappChannelOutbound", () => { preserveLeadingWhitespace: true, }); }); + + it("backs declared message adapter capabilities with delivery proofs", async () => { + const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid-1" })); + + await verifyChannelMessageAdapterCapabilityProofs({ + adapterName: "whatsappMessage", + adapter: whatsappMessageAdapter, + proofs: { + text: async () => { + const result = await whatsappMessageAdapter.send.text?.({ + cfg: {} as never, + to: "5511999999999@c.us", + text: "hello", + deps: { whatsapp: sendWhatsApp }, + } as Parameters>[0] & { + deps: { whatsapp: typeof sendWhatsApp }; + }); + expect(sendWhatsApp).toHaveBeenLastCalledWith("5511999999999@c.us", "hello", { + verbose: false, + cfg: {}, + accountId: undefined, + gifPlayback: undefined, + quotedMessageKey: undefined, + }); + expect(result?.receipt.platformMessageIds).toEqual(["wa-1"]); + }, + replyTo: async () => { + const result = await whatsappMessageAdapter.send.text?.({ + cfg: {} as never, + to: "5511999999999@c.us", + text: "reply", + replyToId: "msg-1", + deps: { whatsapp: sendWhatsApp }, + } as Parameters>[0] & { + deps: { whatsapp: typeof sendWhatsApp }; + }); + expect(sendWhatsApp).not.toHaveBeenCalledWith( + "5511999999999@c.us", + "reply", + expect.anything(), + ); + expect(hoisted.sendMessageWhatsApp).toHaveBeenLastCalledWith( + "5511999999999@c.us", + "reply", + { + verbose: false, + cfg: {}, + accountId: undefined, + gifPlayback: undefined, + quotedMessageKey: { + id: "msg-1", + remoteJid: "5511999999999@c.us", + fromMe: false, + participant: undefined, + messageText: undefined, + }, + preserveLeadingWhitespace: true, + }, + ); + expect(result?.receipt.platformMessageIds).toEqual(["wa-1"]); + }, + messageSendingHooks: () => { + expect(whatsappMessageAdapter.send.text).toBeTypeOf("function"); + }, + }, + }); + }); }); diff --git a/extensions/whatsapp/src/outbound-adapter.poll.test.ts b/extensions/whatsapp/src/outbound-adapter.poll.test.ts deleted file mode 100644 index cf45e2418a8b..000000000000 --- a/extensions/whatsapp/src/outbound-adapter.poll.test.ts +++ /dev/null @@ -1,63 +0,0 @@ -// Whatsapp tests cover outbound adapter.poll plugin behavior. -import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts"; -import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; - -const hoisted = vi.hoisted(() => ({ - sendPollWhatsApp: vi.fn(async () => ({ messageId: "poll-1", toJid: "1555@s.whatsapp.net" })), - sendReactionWhatsApp: vi.fn(async () => undefined), -})); - -vi.mock("openclaw/plugin-sdk/runtime-env", async () => { - const actual = await vi.importActual( - "openclaw/plugin-sdk/runtime-env", - ); - return { - ...actual, - shouldLogVerbose: () => false, - }; -}); - -vi.mock("./send.js", () => ({ - sendPollWhatsApp: hoisted.sendPollWhatsApp, - sendReactionWhatsApp: hoisted.sendReactionWhatsApp, -})); - -let whatsappOutbound: typeof import("./outbound-adapter.js").whatsappOutbound; - -describe("whatsappOutbound sendPoll", () => { - beforeAll(async () => { - ({ whatsappOutbound } = await import("./outbound-adapter.js")); - }); - - beforeEach(() => { - hoisted.sendPollWhatsApp.mockClear(); - hoisted.sendReactionWhatsApp.mockClear(); - }); - - it("threads cfg through poll send options", async () => { - const cfg = { marker: "resolved-cfg" } as OpenClawConfig; - const poll = { - question: "Lunch?", - options: ["Pizza", "Sushi"], - maxSelections: 1, - }; - - const result = await whatsappOutbound.sendPoll!({ - cfg, - to: "+1555", - poll, - accountId: "work", - }); - - expect(hoisted.sendPollWhatsApp).toHaveBeenCalledWith("+1555", poll, { - verbose: false, - accountId: "work", - cfg, - }); - expect(result).toEqual({ - channel: "whatsapp", - messageId: "poll-1", - toJid: "1555@s.whatsapp.net", - }); - }); -}); diff --git a/extensions/whatsapp/src/outbound-adapter.sendpayload.test.ts b/extensions/whatsapp/src/outbound-adapter.sendpayload.test.ts deleted file mode 100644 index 880ec5fd84d2..000000000000 --- a/extensions/whatsapp/src/outbound-adapter.sendpayload.test.ts +++ /dev/null @@ -1,214 +0,0 @@ -// Whatsapp tests cover outbound adapter.sendpayload plugin behavior. -import { describe, expect, it, vi } from "vitest"; -import { whatsappOutbound } from "./outbound-adapter.js"; - -describe("whatsappOutbound sendPayload", () => { - it("trims leading whitespace for direct text sends", async () => { - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendText!({ - cfg: {}, - to: "5511999999999@c.us", - text: "\n \thello", - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenCalledWith("5511999999999@c.us", "hello", { - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - }); - }); - - it("uses the same final sanitizer stack for direct text sends", async () => { - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendText!({ - cfg: {}, - to: "5511999999999@c.us", - text: [ - "Before", - "", - ' ', - ' hidden', - " ", - "", - "
After
", - ].join("\n"), - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenCalledWith("5511999999999@c.us", "Before\n\nAfter\n", { - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - }); - }); - - it("trims leading whitespace for direct media captions", async () => { - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendMedia!({ - cfg: {}, - to: "5511999999999@c.us", - text: "\n \tcaption", - mediaUrl: "/tmp/test.png", - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenCalledWith("5511999999999@c.us", "caption", { - verbose: false, - cfg: {}, - mediaUrl: "/tmp/test.png", - mediaLocalRoots: undefined, - accountId: undefined, - gifPlayback: undefined, - }); - }); - - it("trims leading whitespace for sendPayload text and caption delivery", async () => { - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { text: "\n\nhello" }, - deps: { sendWhatsApp }, - }); - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { text: "\n\ncaption", mediaUrl: "/tmp/test.png" }, - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenNthCalledWith( - 1, - "5511999999999@c.us", - "hello", - expect.objectContaining({ - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - onDeliveryResult: expect.any(Function), - }), - ); - expect(sendWhatsApp).toHaveBeenNthCalledWith( - 2, - "5511999999999@c.us", - "caption", - expect.objectContaining({ - verbose: false, - cfg: {}, - mediaUrl: "/tmp/test.png", - mediaLocalRoots: undefined, - accountId: undefined, - gifPlayback: undefined, - onDeliveryResult: expect.any(Function), - }), - ); - }); - - it("preserves audioAsVoice from payload media sends", async () => { - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { text: "voice", mediaUrl: "/tmp/voice.ogg", audioAsVoice: true }, - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenCalledWith( - "5511999999999@c.us", - "voice", - expect.objectContaining({ - verbose: false, - cfg: {}, - mediaUrl: "/tmp/voice.ogg", - mediaLocalRoots: undefined, - audioAsVoice: true, - accountId: undefined, - gifPlayback: undefined, - onDeliveryResult: expect.any(Function), - }), - ); - }); - - it("drops blank mediaUrls before sending payload media", async () => { - const sendWhatsApp = vi.fn(async () => ({ messageId: "wa-1", toJid: "jid" })); - - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { - text: "\n\ncaption", - mediaUrls: [" ", " /tmp/voice.ogg "], - }, - deps: { sendWhatsApp }, - }); - - expect(sendWhatsApp).toHaveBeenCalledTimes(1); - expect(sendWhatsApp).toHaveBeenCalledWith( - "5511999999999@c.us", - "caption", - expect.objectContaining({ - verbose: false, - cfg: {}, - mediaUrl: "/tmp/voice.ogg", - mediaLocalRoots: undefined, - accountId: undefined, - gifPlayback: undefined, - onDeliveryResult: expect.any(Function), - }), - ); - }); - - it("skips whitespace-only text payloads", async () => { - const sendWhatsApp = vi.fn(); - - const result = await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { text: "\n \t" }, - deps: { sendWhatsApp }, - }); - - expect(result).toEqual({ channel: "whatsapp", messageId: "" }); - expect(sendWhatsApp).not.toHaveBeenCalled(); - }); - - it("suppresses routed error payloads", async () => { - const sendWhatsApp = vi.fn(); - - const result = await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { text: "provider exploded", isError: true }, - deps: { sendWhatsApp }, - }); - - expect(result).toEqual({ channel: "whatsapp", messageId: "" }); - expect(sendWhatsApp).not.toHaveBeenCalled(); - }); - - it("sanitizes HTML-only text to whitespace-only payload", () => { - expect( - whatsappOutbound - .sanitizeText?.({ - text: "

", - payload: { text: "

" }, - }) - ?.trim(), - ).toBe(""); - }); -}); diff --git a/extensions/whatsapp/src/outbound-adapter.ts b/extensions/whatsapp/src/outbound-adapter.ts deleted file mode 100644 index a0945c493f69..000000000000 --- a/extensions/whatsapp/src/outbound-adapter.ts +++ /dev/null @@ -1,31 +0,0 @@ -// Whatsapp plugin module implements outbound adapter behavior. -import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk/channel-send-result"; -import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime"; -import { chunkText } from "openclaw/plugin-sdk/reply-chunking"; -import { shouldLogVerbose } from "openclaw/plugin-sdk/runtime-env"; -import { createWhatsAppOutboundBase } from "./outbound-base.js"; -import { normalizeWhatsAppPayloadText } from "./outbound-media-contract.js"; -import { resolveWhatsAppOutboundTarget } from "./resolve-outbound-target.js"; - -const loadWhatsAppSendModule = createLazyRuntimeModule(() => import("./send.js")); - -function normalizeOutboundText(text: string | undefined): string { - return normalizeWhatsAppPayloadText(text); -} - -export const whatsappOutbound: ChannelOutboundAdapter = createWhatsAppOutboundBase({ - chunker: chunkText, - sendMessageWhatsApp: async (to, text, options) => - await ( - await loadWhatsAppSendModule() - ).sendMessageWhatsApp(to, normalizeOutboundText(text), { - ...options, - }), - sendPollWhatsApp: async (to, poll, options) => - await (await loadWhatsAppSendModule()).sendPollWhatsApp(to, poll, options), - shouldLogVerbose: () => shouldLogVerbose(), - resolveTarget: ({ to, allowFrom, mode }) => - resolveWhatsAppOutboundTarget({ to, allowFrom, mode }), - normalizeText: normalizeOutboundText, - skipEmptyText: true, -}); diff --git a/extensions/whatsapp/src/outbound-payload.contract.test.ts b/extensions/whatsapp/src/outbound-payload.contract.test.ts deleted file mode 100644 index f54613a857b8..000000000000 --- a/extensions/whatsapp/src/outbound-payload.contract.test.ts +++ /dev/null @@ -1,217 +0,0 @@ -// Whatsapp tests cover outbound payload.contract plugin behavior. -import { - installChannelOutboundPayloadContractSuite, - primeChannelOutboundSendMock, - type OutboundPayloadHarnessParams, -} from "openclaw/plugin-sdk/channel-contract-testing"; -import { - verifyChannelMessageAdapterCapabilityProofs, - verifyDurableFinalCapabilityProofs, -} from "openclaw/plugin-sdk/channel-outbound"; -import { beforeEach, describe, expect, it, vi } from "vitest"; -import { whatsappMessageAdapter } from "./channel-outbound.js"; -import { whatsappOutbound } from "./outbound-adapter.js"; - -const hoisted = vi.hoisted(() => ({ - sendMessageWhatsApp: vi.fn(async () => ({ messageId: "wa-live-1", toJid: "jid-live" })), - sendPollWhatsApp: vi.fn(async () => ({ messageId: "poll-live-1", toJid: "jid-live" })), -})); - -vi.mock("./send.js", () => ({ - sendMessageWhatsApp: hoisted.sendMessageWhatsApp, - sendPollWhatsApp: hoisted.sendPollWhatsApp, -})); - -function createWhatsAppHarness(params: OutboundPayloadHarnessParams) { - const sendWhatsApp = vi.fn(); - primeChannelOutboundSendMock(sendWhatsApp, { messageId: "wa-1" }, params.sendResults); - const ctx = { - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: params.payload, - deps: { - whatsapp: sendWhatsApp, - }, - }; - return { - run: async () => await whatsappOutbound.sendPayload!(ctx), - sendMock: sendWhatsApp, - to: ctx.to, - }; -} - -describe("WhatsApp outbound payload contract", () => { - beforeEach(() => { - vi.clearAllMocks(); - }); - - installChannelOutboundPayloadContractSuite({ - channel: "whatsapp", - chunking: { mode: "split", longTextLength: 5000, maxChunkLength: 4000 }, - createHarness: createWhatsAppHarness, - }); - - it("normalizes blank mediaUrls before contract delivery", async () => { - const sendWhatsApp = vi.fn(); - primeChannelOutboundSendMock(sendWhatsApp, { messageId: "wa-1" }); - - await whatsappOutbound.sendPayload!({ - cfg: {}, - to: "5511999999999@c.us", - text: "", - payload: { - text: "\n\ncaption", - mediaUrls: [" ", " /tmp/voice.ogg "], - }, - deps: { - whatsapp: sendWhatsApp, - }, - }); - - expect(sendWhatsApp).toHaveBeenCalledTimes(1); - expect(sendWhatsApp).toHaveBeenCalledWith( - "5511999999999@c.us", - "caption", - expect.objectContaining({ - verbose: false, - cfg: {}, - mediaUrl: "/tmp/voice.ogg", - mediaAccess: undefined, - mediaLocalRoots: undefined, - mediaReadFile: undefined, - accountId: undefined, - gifPlayback: undefined, - onDeliveryResult: expect.any(Function), - }), - ); - }); - - it("backs declared durable final capabilities with delivery proofs", async () => { - const sendWhatsApp = vi.fn(); - primeChannelOutboundSendMock(sendWhatsApp, { messageId: "wa-1", toJid: "jid-1" }); - - const proveText = async () => { - await whatsappOutbound.sendText!({ - cfg: {} as never, - to: "5511999999999@c.us", - text: " hello ", - deps: { whatsapp: sendWhatsApp }, - }); - expect(sendWhatsApp).toHaveBeenLastCalledWith("5511999999999@c.us", "hello", { - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - quotedMessageKey: undefined, - }); - }; - const proveReplyTo = async () => { - await whatsappOutbound.sendText!({ - cfg: {} as never, - to: "5511999999999@c.us", - text: "reply", - replyToId: "msg-1", - deps: { whatsapp: sendWhatsApp }, - }); - expect(sendWhatsApp).not.toHaveBeenCalledWith( - "5511999999999@c.us", - "reply", - expect.anything(), - ); - expect(hoisted.sendMessageWhatsApp).toHaveBeenLastCalledWith("5511999999999@c.us", "reply", { - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - quotedMessageKey: { - id: "msg-1", - remoteJid: "5511999999999@c.us", - fromMe: false, - participant: undefined, - messageText: undefined, - }, - }); - }; - - await verifyDurableFinalCapabilityProofs({ - adapterName: "whatsappOutbound", - capabilities: whatsappOutbound.deliveryCapabilities?.durableFinal, - proofs: { - text: proveText, - replyTo: proveReplyTo, - messageSendingHooks: () => { - expect(whatsappOutbound.sendText).toBeTypeOf("function"); - }, - }, - }); - }); - - it("backs declared message adapter capabilities with delivery proofs", async () => { - const sendWhatsApp = vi.fn(); - primeChannelOutboundSendMock(sendWhatsApp, { messageId: "wa-1", toJid: "jid-1" }); - - await verifyChannelMessageAdapterCapabilityProofs({ - adapterName: "whatsappMessage", - adapter: whatsappMessageAdapter, - proofs: { - text: async () => { - const result = await whatsappMessageAdapter.send.text?.({ - cfg: {} as never, - to: "5511999999999@c.us", - text: "hello", - deps: { whatsapp: sendWhatsApp }, - } as Parameters>[0] & { - deps: { whatsapp: typeof sendWhatsApp }; - }); - expect(sendWhatsApp).toHaveBeenLastCalledWith("5511999999999@c.us", "hello", { - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - quotedMessageKey: undefined, - }); - expect(result?.receipt.platformMessageIds).toEqual(["wa-1"]); - }, - replyTo: async () => { - const result = await whatsappMessageAdapter.send.text?.({ - cfg: {} as never, - to: "5511999999999@c.us", - text: "reply", - replyToId: "msg-1", - deps: { whatsapp: sendWhatsApp }, - } as Parameters>[0] & { - deps: { whatsapp: typeof sendWhatsApp }; - }); - expect(sendWhatsApp).not.toHaveBeenCalledWith( - "5511999999999@c.us", - "reply", - expect.anything(), - ); - expect(hoisted.sendMessageWhatsApp).toHaveBeenLastCalledWith( - "5511999999999@c.us", - "reply", - { - verbose: false, - cfg: {}, - accountId: undefined, - gifPlayback: undefined, - quotedMessageKey: { - id: "msg-1", - remoteJid: "5511999999999@c.us", - fromMe: false, - participant: undefined, - messageText: undefined, - }, - preserveLeadingWhitespace: true, - }, - ); - expect(result?.receipt.platformMessageIds).toEqual(["wa-live-1"]); - }, - messageSendingHooks: () => { - expect(whatsappMessageAdapter.send.text).toBeTypeOf("function"); - }, - }, - }); - }); -}); diff --git a/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts b/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts index d85e51374ec1..b914523d5443 100644 --- a/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts +++ b/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts @@ -56,7 +56,7 @@ const RUNTIME_API_EXPORT_GUARDS: Record = { 'export { auditDiscordChannelPermissions, collectDiscordAuditChannelIds, fetchDiscordApplicationId, fetchDiscordApplicationSummary, listDiscordDirectoryGroupsLive, listDiscordDirectoryPeersLive, parseApplicationIdFromToken, probeDiscord, resolveDiscordChannelAllowlist, resolveDiscordPrivilegedIntentsFromFlags, resolveDiscordUserAllowlist, setDiscordRuntime, type DiscordApplicationSummary, type DiscordChannelResolution, type DiscordPrivilegedIntentsSummary, type DiscordPrivilegedIntentStatus, type DiscordProbe, type DiscordUserResolution } from "./runtime-api.lookup.js";', 'export { DISCORD_ATTACHMENT_IDLE_TIMEOUT_MS, DISCORD_ATTACHMENT_TOTAL_TIMEOUT_MS, DISCORD_DEFAULT_INBOUND_WORKER_TIMEOUT_MS, DISCORD_DEFAULT_LISTENER_TIMEOUT_MS, allowListMatches, clearGateways, clearPresences, createDiscordGatewayPlugin, createDiscordMessageHandler, createDiscordNativeCommand, getGateway, getPresence, isAbortError, isDiscordGroupAllowedByPolicy, monitorDiscordProvider, normalizeDiscordAllowList, normalizeDiscordInboundWorkerTimeoutMs, normalizeDiscordListenerTimeoutMs, normalizeDiscordSlug, presenceCacheSize, registerDiscordListener, registerGateway, resolveDiscordChannelConfig, resolveDiscordChannelConfigWithFallback, resolveDiscordCommandAuthorized, resolveDiscordGatewayIntents, resolveDiscordGuildEntry, resolveDiscordReplyTarget, resolveDiscordShouldRequireMention, resolveGroupDmAllow, runDiscordTaskWithTimeout, sanitizeDiscordThreadName, setPresence, shouldEmitDiscordReactionNotification, unregisterGateway, waitForDiscordGatewayPluginRegistration, type DiscordAllowList, type DiscordChannelConfigResolved, type DiscordGuildEntryResolved, type DiscordMessageEvent, type DiscordMessageHandler, type MonitorDiscordOpts } from "./runtime-api.monitor.js";', 'export { DiscordSendError, addRoleDiscord, banMemberDiscord, createChannelDiscord, createScheduledEventDiscord, createThreadDiscord, deleteChannelDiscord, deleteMessageDiscord, editChannelDiscord, editDiscordComponentMessage, editMessageDiscord, fetchChannelInfoDiscord, fetchChannelPermissionsDiscord, fetchMemberGuildPermissionsDiscord, fetchMemberInfoDiscord, fetchMessageDiscord, fetchReactionsDiscord, fetchRoleInfoDiscord, fetchVoiceStatusDiscord, hasAllGuildPermissionsDiscord, hasAnyGuildPermissionDiscord, kickMemberDiscord, listGuildChannelsDiscord, listGuildEmojisDiscord, listPinsDiscord, listScheduledEventsDiscord, listThreadsDiscord, moveChannelDiscord, pinMessageDiscord, reactMessageDiscord, readMessagesDiscord, registerBuiltDiscordComponentMessage, removeChannelPermissionDiscord, removeOwnReactionsDiscord, removeReactionDiscord, removeRoleDiscord, resolveDiscordOutboundSessionRoute, resolveEventCoverImage, searchMessagesDiscord, sendDiscordComponentMessage, sendMessageDiscord, sendPollDiscord, sendStickerDiscord, sendTypingDiscord, sendVoiceMessageDiscord, sendWebhookMessageDiscord, setChannelPermissionDiscord, timeoutMemberDiscord, unpinMessageDiscord, uploadEmojiDiscord, uploadStickerDiscord, type DiscordChannelCreate, type DiscordChannelEdit, type DiscordChannelMove, type DiscordChannelPermissionSet, type DiscordEmojiUpload, type DiscordMessageEdit, type DiscordMessageQuery, type DiscordModerationTarget, type DiscordPermissionsSummary, type DiscordReactionRuntimeContext, type DiscordReactionSummary, type DiscordReactionUser, type DiscordReactOpts, type DiscordRoleChange, type DiscordRuntimeAccountContext, type DiscordSearchQuery, type DiscordSendResult, type DiscordStickerUpload, type DiscordThreadCreate, type DiscordThreadList, type DiscordTimeoutTarget, type ResolveDiscordOutboundSessionRouteParams } from "./runtime-api.send.js";', - 'export { testing as __testing, testing, autoBindSpawnedDiscordSubagent, createNoopThreadBindingManager, createThreadBindingManager, formatThreadBindingDurationLabel, getThreadBindingManager, listThreadBindingsBySessionKey, listThreadBindingsForAccount, reconcileAcpThreadBindingsOnStartup, resolveDiscordThreadBindingIdleTimeoutMs, resolveDiscordThreadBindingMaxAgeMs, resolveThreadBindingIdleTimeoutMs, resolveThreadBindingInactivityExpiresAt, resolveThreadBindingIntroText, resolveThreadBindingMaxAgeExpiresAt, resolveThreadBindingMaxAgeMs, resolveThreadBindingPersona, resolveThreadBindingPersonaFromRecord, resolveThreadBindingsEnabled, resolveThreadBindingThreadName, setThreadBindingIdleTimeoutBySessionKey, setThreadBindingMaxAgeBySessionKey, unbindThreadBindingsBySessionKey, type AcpThreadBindingReconciliationResult, type ThreadBindingManager, type ThreadBindingRecord, type ThreadBindingTargetKind } from "./runtime-api.threads.js";', + 'export { autoBindSpawnedDiscordSubagent, createNoopThreadBindingManager, createThreadBindingManager, formatThreadBindingDurationLabel, getThreadBindingManager, listThreadBindingsBySessionKey, listThreadBindingsForAccount, reconcileAcpThreadBindingsOnStartup, resolveDiscordThreadBindingIdleTimeoutMs, resolveDiscordThreadBindingMaxAgeMs, resolveThreadBindingIdleTimeoutMs, resolveThreadBindingInactivityExpiresAt, resolveThreadBindingIntroText, resolveThreadBindingMaxAgeExpiresAt, resolveThreadBindingMaxAgeMs, resolveThreadBindingPersona, resolveThreadBindingPersonaFromRecord, resolveThreadBindingsEnabled, resolveThreadBindingThreadName, setThreadBindingIdleTimeoutBySessionKey, setThreadBindingMaxAgeBySessionKey, unbindThreadBindingsBySessionKey, type AcpThreadBindingReconciliationResult, type ThreadBindingManager, type ThreadBindingRecord, type ThreadBindingTargetKind } from "./runtime-api.threads.js";', ], [contractPluginPath({ rootDir: ROOT_DIR, pluginId: "imessage", relativePath: "runtime-api.ts" })]: [ From 31aa7c7c75da0c0c96b8f796c6f9a7a2c6c06c62 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:20:27 -0700 Subject: [PATCH 070/165] refactor(agents): split cli-runner into concept modules (#122442) * refactor(agents): split CLI runner concepts * chore(lint): ratchet cli-runner max-lines baseline * refactor(agents): remove stale runner import * refactor(agents): preserve cleanup error typing * refactor(agents): disambiguate CLI backend predicate * test(agents): align code-mode pending boundary Fixes red main: both host calls are unsettled when the guest snapshot is first parked; later waits still prove that settled calls are filtered. * test(agents): tolerate code-mode settlement race Fixes red main: the fast host call may settle as the guest snapshot is parked, while the deliberately slow call must remain pending. --- config/max-lines-baseline.txt | 1 - src/agents/cli-runner.ts | 1303 ++--------------- src/agents/cli-runner/cli-run-recovery.ts | 207 +++ .../cli-run-settlement.test.ts} | 2 +- src/agents/cli-runner/cli-run-settlement.ts | 657 +++++++++ src/agents/cli-runner/cli-run-transcript.ts | 404 +++++ src/agents/code-mode.wait.test.ts | 5 +- 7 files changed, 1370 insertions(+), 1209 deletions(-) create mode 100644 src/agents/cli-runner/cli-run-recovery.ts rename src/agents/{cli-runner.binding-flush.test.ts => cli-runner/cli-run-settlement.test.ts} (99%) create mode 100644 src/agents/cli-runner/cli-run-settlement.ts create mode 100644 src/agents/cli-runner/cli-run-transcript.ts diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt index e9a9c6e15748..55506e75e08b 100644 --- a/config/max-lines-baseline.txt +++ b/config/max-lines-baseline.txt @@ -336,7 +336,6 @@ src/agents/btw.ts src/agents/cli-auth-epoch.test.ts src/agents/cli-runner.reliability.test.ts src/agents/cli-runner.spawn.test.ts -src/agents/cli-runner.ts src/agents/cli-runner/execute.supervisor-capture.test.ts src/agents/cli-runner/prepare.test.ts src/agents/cli-runner/prepare.ts diff --git a/src/agents/cli-runner.ts b/src/agents/cli-runner.ts index da6028b34617..1ca4aa5348ca 100644 --- a/src/agents/cli-runner.ts +++ b/src/agents/cli-runner.ts @@ -1,11 +1,7 @@ /** * Top-level CLI-backed agent runner orchestration. */ -import { setReplyPayloadMetadata, type ReplyPayload } from "../auto-reply/reply-payload.js"; import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js"; -import { resolveSessionStorePathCore } from "../config/sessions/paths.js"; -import { patchSessionEntryCore } from "../config/sessions/session-accessor.js"; -import { appendExactAssistantMessageToSessionTranscript } from "../config/sessions/transcript.js"; import { buildGenericCliContextEngineHostSupport } from "../context-engine/host-compat.js"; import { assertAgentRunLifecycleGenerationCurrent, @@ -26,30 +22,45 @@ import { } from "../plugins/hook-agent-context.js"; import { resolveBlockMessage } from "../plugins/hook-decision-types.js"; import { getGlobalHookRunner } from "../plugins/hook-runner-global.js"; -import { resolveAgentIdFromSessionKey } from "../routing/session-key.js"; import { - externalCliDiscoveryForProviderAuth, loadAuthProfileStoreForRuntime, markAuthProfileFailure, markAuthProfileSuccess, - type AuthProfileStore, } from "./auth-profiles.js"; -import { isHeartbeatLifecycleRunKind } from "./bootstrap-mode.js"; -import { - resolveCliRuntimeArtifactFingerprint, - resolveCliRuntimeOwnerFingerprint, -} from "./cli-auth-epoch.js"; import { resolveCliBackendConfig } from "./cli-backends.js"; -import type { CliOutput } from "./cli-output-contracts.js"; -import { CliAuthProfilePreparationError } from "./cli-runner/auth-profile-preparation-error.js"; import { acceptsClaudeLive } from "./cli-runner/claude-live-session-policy.js"; +import { + resolveCliSessionId, + runCliRecovery, + type CliRecoveryOptions, +} from "./cli-runner/cli-run-recovery.js"; +import { + assertCliRuntimeBinding, + buildBlockedCliRunResult, + buildCliDeliveredFailure, + buildCliRunResult, + cliRunSettlementDeps, + isClaudeCliBackend, + resolveCliSourceReplyMirror, + settleCliBackendOutcome, + settleCliPreparationError, + settlePreparedCliRun, +} from "./cli-runner/cli-run-settlement.js"; +import { + buildCliHookAssistantMessage, + buildCliHookUserMessage, + finalizeCliContextEngineTurn, + persistApprovedCliUserTurnTranscript, + persistCliAssistantTranscript, + persistCliRunBlock, + runCliAgentEndHook, +} from "./cli-runner/cli-run-transcript.js"; import { attachCliMessagingDeliveryEvidence, getCliMessagingDeliveryEvidence, } from "./cli-runner/delivery-evidence.js"; import { createCliFailoverError } from "./cli-runner/exit-error.js"; import { cliBackendLog, formatCliBackendOutputDigest } from "./cli-runner/log.js"; -import { hashCliReseedPrompt } from "./cli-runner/reseed-envelope.js"; import { runClaudeCliAgentTurnWithDiagnostics, type ClaudeCliRunDiagnosticLifecycle, @@ -58,51 +69,20 @@ import { loadCliSessionContextEngineMessages, loadCliSessionHistoryMessages, } from "./cli-runner/session-history.js"; -import type { - CliReusableSession, - PreparedCliRunContext, - RunCliAgentParams, -} from "./cli-runner/types.js"; +import type { PreparedCliRunContext, RunCliAgentParams } from "./cli-runner/types.js"; import { claudeCliSessionTranscriptHasContent as claudeCliSessionTranscriptHasContentImpl } from "./command/attempt-execution.helpers.js"; import type { EmbeddedAgentRunResult } from "./embedded-agent-runner.js"; import { waitForDeferredTurnMaintenanceForSession } from "./embedded-agent-runner/context-engine-maintenance.js"; -import { resolveExplicitFinalSourceReplyDeliveryEvidence } from "./embedded-agent-runner/delivery-evidence.js"; -import { resolveAuthProfileFailureReason } from "./embedded-agent-runner/run/auth-profile-failure-policy.js"; -import { buildEmbeddedRunPayloads } from "./embedded-agent-runner/run/payloads.js"; -import { coerceToFailoverError, FailoverError, isFailoverError } from "./failover-error.js"; -import { - awaitAgentEndSideEffects, - runAgentEndSideEffects, -} from "./harness/agent-end-side-effects.js"; -import { - bootstrapHarnessContextEngine, - finalizeHarnessContextEngineTurn, - runHarnessContextEngineMaintenance, -} from "./harness/context-engine-lifecycle.js"; +import { bootstrapHarnessContextEngine } from "./harness/context-engine-lifecycle.js"; import { buildAgentHookContext } from "./harness/hook-context.js"; -import { runAgentHarnessBeforeMessageWriteHook } from "./harness/hook-helpers.js"; import { buildAgentHookConversationMessages } from "./harness/hook-history.js"; import { runAgentHarnessLlmInputHook, runAgentHarnessLlmOutputHook, } from "./harness/lifecycle-hook-helpers.js"; -import type { AgentMessage } from "./runtime/index.js"; -import { SessionManager } from "./sessions/session-manager.js"; -import { buildAssistantMessage, buildUsageWithNoCost } from "./stream-message-shared.js"; const log = createSubsystemLogger("agents/cli-runner"); - -const cliRunnerDeps = { - claudeCliSessionTranscriptHasContent: claudeCliSessionTranscriptHasContentImpl, - delay: async (delayMs: number) => { - await new Promise((resolve) => { - setTimeout(resolve, delayMs); - }); - }, - loadAuthProfileStoreForRuntime, - markAuthProfileFailure, - markAuthProfileSuccess, -}; +const cliRunnerDeps = cliRunSettlementDeps; /** Overrides top-level CLI runner dependencies for tests. */ export function setCliRunnerTestDeps(overrides: Partial): void { @@ -122,104 +102,6 @@ export function restoreCliRunnerTestDeps(): void { cliRunnerDeps.markAuthProfileSuccess = markAuthProfileSuccess; } -async function settleCliAuthProfile(params: { - store: AuthProfileStore; - profileId: string; - provider: string; - agentDir?: string; - terminal: - | { outcome: "success" } - | { - outcome: "failure"; - error: unknown; - config?: RunCliAgentParams["config"]; - runId: string; - modelId?: string; - }; -}): Promise { - try { - if (params.terminal.outcome === "success") { - await cliRunnerDeps.markAuthProfileSuccess({ - store: params.store, - profileId: params.profileId, - provider: params.provider, - agentDir: params.agentDir, - }); - return; - } - const error = params.terminal.error; - const reason = resolveAuthProfileFailureReason({ - failoverReason: isFailoverError(error) ? error.reason : null, - providerStarted: - isFailoverError(error) && error.reason === "timeout" - ? error.cliTimeout?.observedActivity - : undefined, - }); - if (reason) { - await cliRunnerDeps.markAuthProfileFailure({ - store: params.store, - profileId: params.profileId, - reason, - cfg: params.terminal.config, - agentDir: params.agentDir, - runId: params.terminal.runId, - modelId: params.terminal.modelId, - }); - } - } catch (error) { - log.warn( - `CLI auth-profile ${params.terminal.outcome} settlement failed: ${formatErrorMessage(error)}`, - ); - } -} - -function isClaudeCliProvider(provider: string): boolean { - return provider.trim().toLowerCase() === "claude-cli"; -} - -function resolveReusableCliSessionId(reusableCliSession: CliReusableSession): string | undefined { - return reusableCliSession.mode === "reuse" || reusableCliSession.mode === "reuse-with-drift" - ? reusableCliSession.sessionId - : undefined; -} - -function shouldRetryFreshCliSessionAfterFailover(params: { - error: FailoverError; - hasHistoryPrompt: boolean; -}): boolean { - if (!params.hasHistoryPrompt) { - return false; - } - switch (params.error.reason) { - case "session_expired": - return true; - case "unknown": - return params.error.code === "cli_unknown_empty_failure"; - case "empty_response": - return params.error.code === "cli_unknown_empty_failure"; - case "format": - return params.error.code === "cli_synthetic_no_response"; - case "timeout": - return params.error.code === "cli_no_output_timeout"; - case "context_overflow": - return params.error.code === "cli_context_overflow"; - default: - return false; - } -} - -function shouldRetryForkedCliSessionAfterFailover(error: FailoverError): boolean { - return error.reason === "timeout" && error.code === "cli_no_output_timeout"; -} - -function isUnsupportedCliResumeAtError(error: unknown, resumeAtArg: string): boolean { - const message = formatErrorMessage(error).toLowerCase(); - return ( - message.includes(resumeAtArg.toLowerCase()) && - /\b(?:unknown|unexpected|unrecognized)\b|\bnot\s+recognized\b/.test(message) - ); -} - /** Checks whether a Claude CLI session binding has reached its transcript file. */ export async function isCliBindingFlushed( sessionId: string | undefined, @@ -227,7 +109,7 @@ export async function isCliBindingFlushed( workspaceDir?: string, options?: { skipTranscriptProbe?: boolean }, ): Promise { - if (!provider || !isClaudeCliProvider(provider)) { + if (!provider || !isClaudeCliBackend(provider)) { return true; } if (!sessionId) { @@ -249,332 +131,6 @@ export async function isCliBindingFlushed( return false; } -async function assertSuccessfulCliRuntimeBindingCurrent( - context: PreparedCliRunContext, -): Promise { - if (!context.runtimeArtifactFingerprint) { - return; - } - const currentArtifact = await resolveCliRuntimeArtifactFingerprint({ - provider: context.params.provider, - config: context.params.config ?? context.contextEngineConfig, - agentId: context.params.agentId, - runtimeArtifactId: context.backendResolved.id, - }); - if (currentArtifact !== context.runtimeArtifactFingerprint) { - throw new Error("CLI executable/package artifact changed during successful inference"); - } - if (!context.runtimeOwnerFingerprint) { - return; - } - const currentOwner = await resolveCliRuntimeOwnerFingerprint({ - provider: context.params.provider, - config: context.params.config ?? context.contextEngineConfig, - ...(context.agentDir ? { agentDir: context.agentDir } : {}), - agentId: context.params.agentId, - runtimeOwnerId: context.backendResolved.id, - ...(context.effectiveAuthProfileId ? { authProfileId: context.effectiveAuthProfileId } : {}), - ...(context.authBindingSkipsLocalCredential ? { skipLocalCredential: true } : {}), - runtimeArtifactFingerprint: currentArtifact, - }); - if (currentOwner !== context.runtimeOwnerFingerprint) { - throw new Error("CLI runtime owner changed during successful inference"); - } -} - -function buildCliHookUserMessage(prompt: string): unknown { - return { - role: "user", - content: prompt, - timestamp: Date.now(), - }; -} - -function buildCliHookAssistantMessage(params: { - text: string; - provider: string; - model: string; - usage?: { - input?: number; - output?: number; - cacheRead?: number; - cacheWrite?: number; - total?: number; - }; -}): unknown { - return { - role: "assistant", - content: [{ type: "text", text: params.text }], - api: "responses", - provider: params.provider, - model: params.model, - ...(params.usage ? { usage: params.usage } : {}), - stopReason: "stop", - timestamp: Date.now(), - }; -} - -function isAgentMessage(value: unknown): value is AgentMessage { - return Boolean(value && typeof value === "object" && "role" in value); -} - -function buildCliContextEngineUserMessage(prompt: string): AgentMessage { - return { - role: "user", - content: prompt, - timestamp: Date.now(), - } as AgentMessage; -} - -function buildCliContextEngineAssistantMessage(params: { - text: string; - provider: string; - model: string; - usage?: { - input?: number; - output?: number; - cacheRead?: number; - cacheWrite?: number; - total?: number; - }; -}): AgentMessage { - return buildCliHookAssistantMessage(params) as AgentMessage; -} - -type CliAgentEndHookParams = Parameters[0]; - -function shouldAwaitCliAgentEndHook(params: RunCliAgentParams): boolean { - return !params.messageChannel && !params.messageProvider; -} - -async function runCliAgentEndHook( - params: RunCliAgentParams, - hookParams: CliAgentEndHookParams, -): Promise { - if (shouldAwaitCliAgentEndHook(params)) { - await awaitAgentEndSideEffects(hookParams); - return; - } - runAgentEndSideEffects(hookParams); -} - -async function persistApprovedCliUserTurnTranscript(params: RunCliAgentParams): Promise { - const recorder = params.userTurnTranscriptRecorder; - const reusingPersistedTurn = params.suppressNextUserMessagePersistence === true; - if (!recorder || (reusingPersistedTurn && !recorder.hasPersisted())) { - return recorder?.isBlocked() === true; - } - - const persisted = await recorder.persistApproved({ - cwd: params.cwd ?? params.workspaceDir, - }); - if (!persisted && !recorder.hasPersisted() && (await recorder.resolveMessage())) { - // A prepared user row can be rejected by before_message_write. Preserve - // that terminal decision so outer transcript mirrors do not retry it. - recorder.markBlocked(); - } - if (persisted && !reusingPersistedTurn) { - try { - const notification = params.onUserMessagePersisted?.(persisted.message); - if (notification) { - void Promise.resolve(notification).catch((error: unknown) => { - log.warn(`CLI user turn persistence notification failed: ${formatErrorMessage(error)}`); - }); - } - } catch (error) { - log.warn(`CLI user turn persistence notification failed: ${formatErrorMessage(error)}`); - } - } - return persisted !== undefined || recorder.hasPersisted() || recorder.isBlocked(); -} - -async function persistCliAssistantTranscript(params: { - runParams: RunCliAgentParams; - text: string; - modelId: string; - usage?: { - input?: number; - output?: number; - cacheRead?: number; - cacheWrite?: number; - total?: number; - }; -}): Promise<{ - owned: boolean; - terminalAnchor?: import("../config/sessions/session-accessor.js").TranscriptEntryAnchor; -}> { - const { runParams } = params; - if (runParams.currentInboundEventKind === "room_event") { - const admission = runParams.userTurnTranscriptRecorder?.getAdmissionReceipt(); - return { - owned: true, - ...(admission ? { terminalAnchor: admission } : {}), - }; - } - if (!params.text) { - const admission = runParams.userTurnTranscriptRecorder?.getAdmissionReceipt(); - return { - owned: false, - ...(admission ? { terminalAnchor: admission } : {}), - }; - } - if (!runParams.persistAssistantTranscript || !runParams.sessionKey) { - return { owned: false }; - } - try { - const result = await appendExactAssistantMessageToSessionTranscript({ - sessionKey: runParams.sessionKey, - agentId: runParams.agentId, - expectedSessionId: runParams.sessionId, - ...(runParams.expectedLifecycleRevision !== undefined - ? { expectedLifecycleRevision: runParams.expectedLifecycleRevision } - : {}), - ...(runParams.expectedWriterRunId !== undefined - ? { expectedWriterRunId: runParams.expectedWriterRunId } - : {}), - storePath: runParams.storePath, - idempotencyKey: `cli-assistant:${runParams.runId}`, - config: runParams.config, - beforeMessageWrite: runAgentHarnessBeforeMessageWriteHook, - message: buildAssistantMessage({ - model: { - api: "cli", - provider: runParams.provider, - id: params.modelId, - }, - content: [{ type: "text", text: params.text }], - stopReason: "stop", - usage: buildUsageWithNoCost({ - input: params.usage?.input, - output: params.usage?.output, - cacheRead: params.usage?.cacheRead, - cacheWrite: params.usage?.cacheWrite, - totalTokens: params.usage?.total, - }), - }), - }); - if (!result.ok) { - log.warn(`CLI assistant transcript persistence skipped: ${result.reason}`); - return { owned: result.code === "blocked" || result.code === "session-rebound" }; - } - return { owned: true, ...(result.anchor ? { terminalAnchor: result.anchor } : {}) }; - } catch (error) { - log.warn(`CLI assistant transcript persistence failed: ${formatErrorMessage(error)}`); - return { owned: false }; - } -} - -async function notifyCliUserMessagePersisted( - params: RunCliAgentParams, - message: Extract, - context: string, -): Promise { - try { - await Promise.resolve(params.onUserMessagePersisted?.(message)); - } catch (err) { - log.warn(`${context} notification failed: ${formatErrorMessage(err)}`); - } -} - -async function finalizeCliContextEngineTurn(params: { - context: PreparedCliRunContext; - historyMessages: unknown[]; - assistantText: string; - terminalAnchor?: import("../config/sessions/session-accessor.js").TranscriptEntryAnchor; - output: Awaited< - ReturnType - >; -}): Promise { - const { context } = params; - if (!context.contextEngine) { - return; - } - - const { params: runParams } = context; - const prePromptMessages = params.historyMessages.filter(isAgentMessage); - const turnMessages: AgentMessage[] = []; - if (context.contextEngineTurnPrompt) { - turnMessages.push(buildCliContextEngineUserMessage(context.contextEngineTurnPrompt)); - } - if (params.assistantText) { - turnMessages.push( - buildCliContextEngineAssistantMessage({ - text: params.assistantText, - provider: runParams.provider, - model: context.modelId, - usage: params.output.usage, - }), - ); - } - - const contextEngineHostSupport = buildGenericCliContextEngineHostSupport({ - backendId: context.backendResolved.id, - }); - const finalizeTurn = async (transcript: { - messagesSnapshot: AgentMessage[]; - prePromptMessageCount: number; - sessionManager?: SessionManager; - withSessionManagerRewriteLock: (operation: () => Promise | T) => Promise; - }) => { - let deferredTurnMaintenance: Promise | undefined; - const result = await finalizeHarnessContextEngineTurn({ - contextEngine: context.contextEngine, - promptError: false, - aborted: runParams.abortSignal?.aborted === true, - yieldAborted: false, - sessionIdUsed: runParams.sessionId, - sessionKey: runParams.sessionKey, - sessionFile: runParams.sessionFile, - isHeartbeat: isHeartbeatLifecycleRunKind(runParams.bootstrapContextRunKind), - messagesSnapshot: transcript.messagesSnapshot, - prePromptMessageCount: transcript.prePromptMessageCount, - sessionManager: transcript.sessionManager, - config: context.contextEngineConfig, - contextEngineHostSupport, - providerId: runParams.provider, - modelId: context.modelId, - runMaintenance: async (maintenanceParams) => - await runHarnessContextEngineMaintenance({ - ...maintenanceParams, - withSessionManagerRewriteLock: transcript.withSessionManagerRewriteLock, - onDeferredMaintenance: (promise) => { - deferredTurnMaintenance = promise; - }, - }), - warn: (message) => log.warn(message), - }); - if (result.postTurnFinalizationSucceeded && deferredTurnMaintenance) { - context.contextEngineDeferredTurnMaintenance = deferredTurnMaintenance; - } - }; - const admission = runParams.userTurnTranscriptRecorder?.getAdmissionReceipt(); - if (runParams.onContextEngineTurnCandidate) { - if (admission && params.terminalAnchor) { - runParams.onContextEngineTurnCandidate({ - boundary: { admission, terminal: params.terminalAnchor }, - sessionIdUsed: runParams.sessionId, - sessionKey: runParams.sessionKey, - sessionTarget: runParams.sessionTarget, - sessionFile: runParams.sessionFile, - promptError: false, - aborted: runParams.abortSignal?.aborted === true, - yieldAborted: false, - contextEngineHostSupport, - providerId: runParams.provider, - modelId: context.modelId, - config: context.contextEngineConfig, - isHeartbeat: isHeartbeatLifecycleRunKind(runParams.bootstrapContextRunKind), - }); - } - } else { - await finalizeTurn({ - messagesSnapshot: [...prePromptMessages, ...turnMessages], - prePromptMessageCount: prePromptMessages.length, - withSessionManagerRewriteLock: async (operation) => await operation(), - }); - } -} - /** Prepares and runs one CLI-backed agent turn. */ export function runCliAgent(paramsInput: RunCliAgentParams): Promise { const lifecycleGeneration = @@ -586,7 +142,7 @@ export function runCliAgent(paramsInput: RunCliAgentParams): Promise - isClaudeCliProvider(params.provider) && + isClaudeCliBackend(params.provider) && areDiagnosticsEnabledForProcess() && hasInternalDiagnosticEventListeners() ? runClaudeCliAgentTurnWithDiagnostics(params, (diagnosticLifecycle) => @@ -671,107 +227,14 @@ async function runCliAgentInternal( try { context = await prepareCliRunContext(params); } catch (error) { - if (error instanceof CliAuthProfilePreparationError) { - const store = cliRunnerDeps.loadAuthProfileStoreForRuntime(error.agentDir, { - externalCli: externalCliDiscoveryForProviderAuth({ - cfg: params.config, - provider: error.provider, - profileId: error.profileId, - }), - }); - await settleCliAuthProfile({ - store, - profileId: error.profileId, - provider: error.provider, - agentDir: error.agentDir, - terminal: { - outcome: "failure", - error, - config: params.config, - runId: params.runId, - modelId: params.model, - }, - }); - } + await settleCliPreparationError(error, params); throw error; } - let result: EmbeddedAgentRunResult | undefined; - let runError: unknown; - try { - result = await runPreparedCliAgent(context, diagnosticLifecycle); - } catch (error) { - runError = error; - } - const terminalRunError = runError; - let cleanupError: unknown; - const recordCleanupError = (error: unknown) => { - cleanupError ??= error; - }; - if (params.cleanupCliLiveSessionOnRunEnd === true) { - try { - const { closeClaudeSession } = await import("./cli-runner/claude-live-registry.js"); - await closeClaudeSession(context, "restart"); - } catch (error) { - recordCleanupError(error); - } - } - if (params.cleanupBundleMcpOnRunEnd === true) { - // The run's session ID is immutable; its session key can already belong to - // a newer run. Never retire the newer runtime or close the shared listener. - try { - const { retireSessionMcpRuntime } = await import("./agent-bundle-mcp-tools.js"); - await retireSessionMcpRuntime({ - sessionId: params.sessionId, - reason: "cli-run-end", - onError: recordCleanupError, - }); - } catch (error) { - recordCleanupError(error); - } - } - if (cleanupError) { - if (runError || result?.didSendViaMessagingTool === true) { - log.warn(`cli run cleanup failed after completion: ${formatErrorMessage(cleanupError)}`); - } else { - diagnosticLifecycle?.setPhase("cleanup"); - runError = - cleanupError instanceof Error ? cleanupError : new Error(formatErrorMessage(cleanupError)); - } - } - // Settle only after backend recovery is exhausted. Recording inside an - // attempt would quarantine a healthy profile for a recovered session fault. - if (context.effectiveAuthProfileId && context.authProfileStore) { - const profileId = context.effectiveAuthProfileId; - const authProfileStore = context.authProfileStore; - if (terminalRunError) { - await settleCliAuthProfile({ - store: authProfileStore, - profileId, - provider: authProfileStore.profiles[profileId]?.provider ?? params.provider, - agentDir: context.agentDir, - terminal: { - outcome: "failure", - error: terminalRunError, - config: params.config, - runId: params.runId, - modelId: context.modelId, - }, - }); - } else if (result?.meta.executionTrace?.attempts?.at(-1)?.result === "success") { - const provider = authProfileStore.profiles[profileId]?.provider ?? params.provider; - await settleCliAuthProfile({ - store: authProfileStore, - profileId, - provider, - agentDir: context.agentDir, - terminal: { outcome: "success" }, - }); - } - } - if (runError) { - throw runError instanceof Error ? runError : new Error(formatErrorMessage(runError)); - } - return result as EmbeddedAgentRunResult; + return await settlePreparedCliRun({ + context, + diagnosticLifecycle, + run: async () => await runPreparedCliAgent(context, diagnosticLifecycle), + }); } /** Runs an already-prepared CLI agent context through hooks and execution. */ @@ -789,7 +252,7 @@ export async function runPreparedCliAgent( }; const sessionBindingDisabled = context.preparedBackend.backend.sessionMode === "none"; const preparedContextAgentMeta = - isClaudeCliProvider(params.provider) && context.contextWindowInfo + isClaudeCliBackend(params.provider) && context.contextWindowInfo ? { contextTokens: context.contextWindowInfo.tokens } : {}; const isolatedCompletion = params.isolatedCompletion === true; @@ -877,268 +340,9 @@ export async function runPreparedCliAgent( durationMs: Date.now() - context.started, }); - const buildBlockedBeforeAgentRunResult = (message: string): EmbeddedAgentRunResult => ({ - payloads: [{ text: message, isError: true }], - meta: { - durationMs: Date.now() - context.started, - finalAssistantVisibleText: message, - finalAssistantRawText: message, - livenessState: "blocked", - error: { - kind: "hook_block", - message, - }, - systemPromptReport: context.systemPromptReport, - executionTrace: { - winnerProvider: params.provider, - winnerModel: context.modelId, - attempts: [ - { - provider: params.provider, - model: context.modelId, - result: "error", - reason: "before_agent_run blocked the run", - }, - ], - fallbackUsed: false, - runner: "cli", - }, - requestShaping: { - ...(params.thinkLevel ? { thinking: params.thinkLevel } : {}), - ...(context.effectiveAuthProfileId ? { authMode: "auth-profile" } : {}), - }, - completion: { - finishReason: "blocked", - stopReason: "blocked", - refusal: true, - }, - agentMeta: { - sessionId: params.sessionId ?? "", - provider: params.provider, - model: context.modelId, - ...preparedContextAgentMeta, - ...(sessionBindingDisabled ? { clearCliSessionBinding: true } : {}), - }, - }, - }); - let deliveredMessagingSideEffect = false; let userTurnHandled = false; - const buildCliSourceReplyMirrorPayloads = ( - evidence: Pick< - CliOutput, - | "didSendViaMessagingTool" - | "didDeliverSourceReplyViaMessageTool" - | "messagingToolSentTargets" - | "messagingToolSourceReplyPayloads" - >, - ): ReplyPayload[] => { - return buildEmbeddedRunPayloads({ - assistantTexts: [], - lastAssistant: undefined, - sessionKey: params.sessionKey ?? "", - provider: params.provider, - model: context.modelId, - didSendViaMessagingTool: evidence.didSendViaMessagingTool, - didDeliverSourceReplyViaMessageTool: evidence.didDeliverSourceReplyViaMessageTool, - messagingToolSentTargets: evidence.messagingToolSentTargets, - messagingToolSourceReplyPayloads: evidence.messagingToolSourceReplyPayloads, - sourceReplyDeliveryMode: params.sourceReplyDeliveryMode, - agentId: params.agentId, - runId: params.runId, - }); - }; - - const resolveCliSourceReplyMirror = ( - evidence: Pick< - CliOutput, - | "didSendViaMessagingTool" - | "didDeliverSourceReplyViaMessageTool" - | "messagingToolSentTargets" - | "messagingToolSourceReplyPayloads" - >, - ) => { - const payloads = buildCliSourceReplyMirrorPayloads(evidence); - const delivered = - payloads.length > 0 || - (params.sourceReplyDeliveryMode === "message_tool_only" && - evidence.didDeliverSourceReplyViaMessageTool === true); - const visibleText = - payloads - .map((payload) => payload.text?.trim() ?? "") - .filter(Boolean) - .join("\n\n") || undefined; - return { payloads, delivered, visibleText }; - }; - - const buildDeliveredFailureResult = ( - error: unknown, - evidence: NonNullable>, - ): EmbeddedAgentRunResult => { - const message = formatErrorMessage(error); - const { payloads } = resolveCliSourceReplyMirror(evidence); - const visiblePayloads = - payloads.length > 0 - ? payloads - : resolveExplicitFinalSourceReplyDeliveryEvidence(evidence) === false - ? [{ text: "The reply stopped after sending progress. Please try again.", isError: true }] - : undefined; - deliveredMessagingSideEffect = true; - return { - ...(visiblePayloads ? { payloads: visiblePayloads } : {}), - meta: { - durationMs: Date.now() - context.started, - systemPromptReport: context.systemPromptReport, - stopReason: "error", - executionTrace: { - winnerProvider: params.provider, - winnerModel: context.modelId, - attempts: [ - { - provider: params.provider, - model: context.modelId, - result: "error", - reason: message, - }, - ], - fallbackUsed: false, - runner: "cli", - }, - requestShaping: { - ...(params.thinkLevel ? { thinking: params.thinkLevel } : {}), - ...(context.effectiveAuthProfileId ? { authMode: "auth-profile" } : {}), - }, - completion: { - finishReason: "error", - stopReason: "error", - refusal: false, - }, - agentMeta: { - sessionId: "", - provider: params.provider, - model: context.modelId, - ...preparedContextAgentMeta, - ...(sessionBindingDisabled || resolveReusableCliSessionId(context.reusableCliSession) - ? { clearCliSessionBinding: true } - : {}), - }, - }, - didSendViaMessagingTool: true, - ...(evidence.didDeliverSourceReplyViaMessageTool - ? { didDeliverSourceReplyViaMessageTool: true } - : {}), - ...(evidence.messagingToolSentTexts?.length - ? { messagingToolSentTexts: evidence.messagingToolSentTexts } - : {}), - ...(evidence.messagingToolSentMediaUrls?.length - ? { messagingToolSentMediaUrls: evidence.messagingToolSentMediaUrls } - : {}), - ...(evidence.messagingToolSentTargets?.length - ? { messagingToolSentTargets: evidence.messagingToolSentTargets } - : {}), - ...(evidence.messagingToolSourceReplyPayloads?.length - ? { messagingToolSourceReplyPayloads: evidence.messagingToolSourceReplyPayloads } - : {}), - }; - }; - - const persistBlockedBeforeAgentRun = async (block: { - message: string; - pluginId: string; - }): Promise => { - const nowMs = Date.now(); - const redactedUserMessage = { - role: "user" as const, - content: [{ type: "text" as const, text: block.message }], - timestamp: nowMs, - idempotencyKey: `hook-block:before_agent_run:user:${params.runId}`, - __openclaw: { - beforeAgentRunBlocked: { - blockedBy: block.pluginId, - blockedAt: nowMs, - }, - }, - }; - try { - const persisted = - await params.userTurnTranscriptRecorder?.persistBlocked(redactedUserMessage); - if (persisted) { - await notifyCliUserMessagePersisted( - params, - persisted.message, - "before_agent_run block user-turn persistence", - ); - return; - } - } catch (err) { - log.warn( - `before_agent_run block: failed to persist canonical CLI user message: ${formatErrorMessage( - err, - )}`, - ); - } - - try { - const sessionKey = params.sessionKey?.trim() || params.sessionId; - const agentId = params.agentId ?? resolveAgentIdFromSessionKey(sessionKey); - let sessionManager = params.sessionManager; - if (!sessionManager) { - const sessionTarget = params.sessionTarget ?? { - agentId, - sessionId: params.sessionId, - sessionKey, - storePath: - params.storePath ?? - resolveSessionStorePathCore(params.config?.session?.store, { - agentId, - }), - }; - const persistedEntry = await patchSessionEntryCore( - sessionTarget, - (entry, patchContext) => { - if (patchContext.existingEntry && entry.sessionId !== sessionTarget.sessionId) { - return null; - } - return { - sessionId: sessionTarget.sessionId, - updatedAt: Date.now(), - }; - }, - { - fallbackEntry: params.sessionEntry - ? undefined - : { sessionId: sessionTarget.sessionId, updatedAt: Date.now() }, - skipMaintenance: true, - }, - ); - if (persistedEntry?.sessionId !== sessionTarget.sessionId) { - // Skip only this stale blocked-message write; the outer runner still returns blocked. - return; - } - sessionManager = SessionManager.open(sessionTarget); - } - sessionManager.appendMessage( - redactedUserMessage as Parameters[0], - ); - sessionManager.flushPendingPersistence(); - } catch (err) { - log.warn( - `before_agent_run block: failed to persist redacted CLI user message: ${formatErrorMessage( - err, - )}`, - ); - } - }; - - const executeCliAttempt = async ( - cliSessionIdToUse?: string, - options?: { - timeoutMs?: number; - forkCliSessionOnResume?: boolean; - resumeAt?: string; - onForkSuccessorPersisted?: (sessionId: string) => void; - }, - ) => { + const executeCliAttempt = async (cliSessionIdToUse?: string, options?: CliRecoveryOptions) => { const timeoutMs = options?.timeoutMs ?? params.timeoutMs; const forkCliSessionOnResume = options?.forkCliSessionOnResume ?? context.params.forkCliSessionOnResume; @@ -1179,7 +383,11 @@ export async function runPreparedCliAgent( ); // Test facades and non-instrumented executors may not signal the boundary. diagnosticLifecycle?.setPhase("resolve"); - const sourceReplyMirror = resolveCliSourceReplyMirror(output); + const sourceReplyMirror = resolveCliSourceReplyMirror({ + evidence: output, + runParams: params, + modelId: context.modelId, + }); const assistantText = sourceReplyMirror.delivered ? (sourceReplyMirror.visibleText ?? "") : output.text.trim(); @@ -1258,211 +466,18 @@ export async function runPreparedCliAgent( }; }; - const buildCliRunResult = (resultParams: { - output: Awaited>; - effectiveCliSessionId?: string; - bindingFlushOk?: boolean; - assistantTranscriptOwned?: boolean; - usedHistoryPrompt: boolean; - }): EmbeddedAgentRunResult => { - const text = resultParams.output.text?.trim(); - const rawText = resultParams.output.rawText?.trim(); - const sourceReplyMirror = resolveCliSourceReplyMirror(resultParams.output); - const finalAssistantVisibleText = sourceReplyMirror.delivered - ? sourceReplyMirror.visibleText - : text; - const payloads = - sourceReplyMirror.payloads.length > 0 - ? sourceReplyMirror.payloads - : sourceReplyMirror.delivered - ? undefined - : text - ? [ - resultParams.assistantTranscriptOwned - ? setReplyPayloadMetadata({ text }, { assistantTranscriptOwned: true }) - : { text }, - ] - : params.allowEmptyAssistantReplyAsSilent === true - ? [{ text: SILENT_REPLY_TOKEN }] - : undefined; - if (resultParams.output.didSendViaMessagingTool) { - deliveredMessagingSideEffect = true; - } - const unflushedCliSessionId = - !sessionBindingDisabled && - resultParams.effectiveCliSessionId && - resultParams.bindingFlushOk === false - ? resultParams.effectiveCliSessionId - : undefined; - const persistedCliSessionId = sessionBindingDisabled - ? undefined - : unflushedCliSessionId - ? undefined - : resultParams.effectiveCliSessionId; - const createdReseedReceipt = - persistedCliSessionId && - resultParams.usedHistoryPrompt && - isClaudeCliProvider(params.provider) && - resultParams.output.finalPromptText !== undefined && - userTurnHandled && - params.sessionId - ? { - version: 1 as const, - promptHash: hashCliReseedPrompt(resultParams.output.finalPromptText), - localSessionId: params.sessionId, - userTurnDisposition: params.userTurnTranscriptRecorder?.hasPersisted() - ? ("persisted" as const) - : ("omitted" as const), - } - : undefined; - const preservedReseedReceipt = - params.cliSessionBinding && persistedCliSessionId === params.cliSessionBinding.sessionId - ? params.cliSessionBinding.reseedReceipt - : undefined; - const reseedReceipt = createdReseedReceipt ?? preservedReseedReceipt; - const agentSessionId = sessionBindingDisabled - ? (params.sessionId ?? "") - : unflushedCliSessionId - ? "" - : (resultParams.effectiveCliSessionId ?? params.sessionId ?? ""); - const yielded = resultParams.output.yielded === true; - const stopReason = yielded ? "end_turn" : "completed"; - - params.onSuccessfulAuthBinding?.({ - ...(context.effectiveAuthProfileId ? { authProfileId: context.effectiveAuthProfileId } : {}), - ...(context.authBindingFingerprint - ? { authFingerprint: context.authBindingFingerprint } - : {}), - ...(!context.authBindingFingerprint && context.runtimeOwnerFingerprint - ? { - runtimeOwnerFingerprint: context.runtimeOwnerFingerprint, - runtimeOwnerKind: "cli-runtime" as const, - runtimeOwnerId: context.backendResolved.id, - } - : {}), - ...(context.runtimeArtifactFingerprint - ? { - runtimeArtifactFingerprint: context.runtimeArtifactFingerprint, - runtimeArtifactId: context.backendResolved.id, - } - : {}), - ...(context.authBindingSkipsLocalCredential ? { skipLocalCredential: true } : {}), - }); - - return { - payloads, - meta: { - durationMs: Date.now() - context.started, - ...(resultParams.output.finalPromptText - ? { finalPromptText: resultParams.output.finalPromptText } - : {}), - ...(finalAssistantVisibleText || rawText - ? { - ...(finalAssistantVisibleText ? { finalAssistantVisibleText } : {}), - ...(rawText ? { finalAssistantRawText: rawText } : {}), - } - : {}), - systemPromptReport: context.systemPromptReport, - ...(yielded ? { yielded: true, livenessState: "paused" as const, stopReason } : {}), - executionTrace: { - winnerProvider: params.provider, - winnerModel: context.modelId, - attempts: [ - { - provider: params.provider, - model: context.modelId, - result: "success", - }, - ], - fallbackUsed: false, - runner: "cli", - }, - requestShaping: { - ...(params.thinkLevel ? { thinking: params.thinkLevel } : {}), - ...(context.effectiveAuthProfileId ? { authMode: "auth-profile" } : {}), - }, - completion: { - finishReason: yielded ? "end_turn" : "stop", - stopReason, - refusal: false, - }, - ...(resultParams.output.toolSummary - ? { toolSummary: resultParams.output.toolSummary } - : {}), - agentMeta: { - sessionId: agentSessionId, - provider: params.provider, - model: context.modelId, - ...preparedContextAgentMeta, - usage: resultParams.output.usage, - ...(resultParams.output.usage ? { lastCallUsage: resultParams.output.usage } : {}), - ...(resultParams.output.diagnosticUsage - ? { diagnosticUsage: resultParams.output.diagnosticUsage } - : {}), - ...(persistedCliSessionId - ? { - cliSessionBinding: { - sessionId: persistedCliSessionId, - ...(context.effectiveAuthProfileId - ? { authProfileId: context.effectiveAuthProfileId } - : {}), - ...(resultParams.output.resumeCheckpointId - ? { resumeCheckpointId: resultParams.output.resumeCheckpointId } - : {}), - ...(context.authEpoch ? { authEpoch: context.authEpoch } : {}), - authEpochVersion: context.authEpochVersion, - ...(context.extraSystemPromptHash - ? { extraSystemPromptHash: context.extraSystemPromptHash } - : {}), - ...(context.messageToolPolicyHash - ? { messageToolPolicyHash: context.messageToolPolicyHash } - : {}), - ...(context.promptToolNamesHash - ? { promptToolNamesHash: context.promptToolNamesHash } - : {}), - ...(context.cwdHash ? { cwdHash: context.cwdHash } : {}), - ...(context.preparedBackend.mcpConfigHash - ? { mcpConfigHash: context.preparedBackend.mcpConfigHash } - : {}), - ...(context.preparedBackend.mcpResumeHash - ? { mcpResumeHash: context.preparedBackend.mcpResumeHash } - : {}), - ...(reseedReceipt ? { reseedReceipt } : {}), - }, - } - : {}), - ...(sessionBindingDisabled || unflushedCliSessionId - ? { clearCliSessionBinding: true } - : {}), - }, - }, - ...(resultParams.output.didSendViaMessagingTool ? { didSendViaMessagingTool: true } : {}), - ...(resultParams.output.didDeliverSourceReplyViaMessageTool - ? { didDeliverSourceReplyViaMessageTool: true } - : {}), - ...(resultParams.output.messagingToolSentTexts?.length - ? { messagingToolSentTexts: resultParams.output.messagingToolSentTexts } - : {}), - ...(resultParams.output.messagingToolSentMediaUrls?.length - ? { messagingToolSentMediaUrls: resultParams.output.messagingToolSentMediaUrls } - : {}), - ...(resultParams.output.messagingToolSentTargets?.length - ? { messagingToolSentTargets: resultParams.output.messagingToolSentTargets } - : {}), - ...(resultParams.output.messagingToolSourceReplyPayloads?.length - ? { messagingToolSourceReplyPayloads: resultParams.output.messagingToolSourceReplyPayloads } - : {}), - }; - }; - const executeRun = async (): Promise => { if (isolatedCompletion) { const { output, usedHistoryPrompt } = await executeCliAttempt(); return buildCliRunResult({ + context, output, bindingFlushOk: true, assistantTranscriptOwned: false, usedHistoryPrompt, + userTurnHandled, + sessionBindingDisabled, + preparedContextAgentMeta, }); } await bootstrapHarnessContextEngine({ @@ -1495,7 +510,7 @@ export async function runPreparedCliAgent( const { output, assistantText, lastAssistant, sourceReplyWasDelivered, usedHistoryPrompt } = result; try { - await assertSuccessfulCliRuntimeBindingCurrent(context); + await assertCliRuntimeBinding(context); const effectiveCliSessionId = output.sessionId ?? fallbackCliSessionId; const assistantTranscript = await persistCliAssistantTranscript({ runParams: params, @@ -1532,11 +547,15 @@ export async function runPreparedCliAgent( hookRunner, }); return buildCliRunResult({ + context, output, effectiveCliSessionId, bindingFlushOk, assistantTranscriptOwned: assistantTranscript.owned, usedHistoryPrompt, + userTurnHandled, + sessionBindingDisabled, + preparedContextAgentMeta, }); } catch (error) { throw attachCliMessagingDeliveryEvidence(error, output); @@ -1555,7 +574,15 @@ export async function runPreparedCliAgent( ctx: hookContext, hookRunner, }); - return buildDeliveredFailureResult(error, evidence); + deliveredMessagingSideEffect = true; + return buildCliDeliveredFailure({ + error, + evidence, + context, + preparedContextAgentMeta, + sessionBindingDisabled, + reusableCliSessionId: resolveCliSessionId(context.reusableCliSession), + }); }; if (hasBeforeAgentRunHooks && hookRunner) { @@ -1583,7 +610,7 @@ export async function runPreparedCliAgent( { outcome: "block", reason: "before_agent_run hook failed" }, { blockedBy: "before_agent_run" }, ); - await persistBlockedBeforeAgentRun({ + await persistCliRunBlock(params, { message: blockMessage, pluginId: "before_agent_run", }); @@ -1592,7 +619,12 @@ export async function runPreparedCliAgent( ctx: hookContext, hookRunner, }); - return buildBlockedBeforeAgentRunResult(blockMessage); + return buildBlockedCliRunResult({ + message: blockMessage, + context, + preparedContextAgentMeta, + sessionBindingDisabled, + }); } const beforeRunDecision = beforeRunResult?.decision; @@ -1600,7 +632,7 @@ export async function runPreparedCliAgent( const blockMessage = resolveBlockMessage(beforeRunDecision, { blockedBy: beforeRunResult?.pluginId ?? "unknown", }); - await persistBlockedBeforeAgentRun({ + await persistCliRunBlock(params, { message: blockMessage, pluginId: beforeRunResult?.pluginId ?? "unknown", }); @@ -1609,7 +641,12 @@ export async function runPreparedCliAgent( ctx: hookContext, hookRunner, }); - return buildBlockedBeforeAgentRunResult(blockMessage); + return buildBlockedCliRunResult({ + message: blockMessage, + context, + preparedContextAgentMeta, + sessionBindingDisabled, + }); } } @@ -1619,156 +656,19 @@ export async function runPreparedCliAgent( ctx: hookContext, hookRunner, }); - const reusableCliSessionId = resolveReusableCliSessionId(context.reusableCliSession); - const resumeCheckpointId = params.cliSessionBinding?.resumeCheckpointId; - let retryableSessionId = reusableCliSessionId; - try { - return await finishCliAttempt( - await executeCliAttempt( - reusableCliSessionId, - params.forkCliSessionOnResume - ? { - onForkSuccessorPersisted: (sessionId) => { - retryableSessionId = sessionId; - }, - } - : undefined, - ), - reusableCliSessionId, - ); - } catch (err) { - const deliveredFailure = await finishDeliveredFailure(err); - if (deliveredFailure) { - return deliveredFailure; - } - let recoveryError = err; - if ( - params.forkCliSessionOnResume && - resumeCheckpointId && - context.preparedBackend.backend.resumeAtArg && - isUnsupportedCliResumeAtError(err, context.preparedBackend.backend.resumeAtArg) - ) { - recoveryError = createCliFailoverError( - "CLI backend cannot resume from the stored checkpoint.", - "session_expired", - cliFailoverContext, - { cause: err }, - ); - } - if (isFailoverError(recoveryError)) { - if ( - !params.forkCliSessionOnResume && - shouldRetryForkedCliSessionAfterFailover(recoveryError) && - retryableSessionId && - resumeCheckpointId && - params.sessionKey && - context.preparedBackend.backend.forkArg && - context.preparedBackend.backend.resumeAtArg && - params.onBeforeForkedCliSessionRetry - ) { - try { - const retryTimeoutMs = params.timeoutMs - (Date.now() - context.started); - if (retryTimeoutMs <= 0) { - throw recoveryError; - } - const forkPrepared = await params.onBeforeForkedCliSessionRetry({ - provider: params.provider, - reason: recoveryError.reason, - sessionId: retryableSessionId, - }); - if (!forkPrepared) { - throw recoveryError; - } - cliBackendLog.warn( - `cli session recovery fork: provider=${params.provider} reason=${recoveryError.reason} sessionKey=${params.sessionKey}`, - ); - return await finishCliAttempt( - await executeCliAttempt(retryableSessionId, { - timeoutMs: retryTimeoutMs, - forkCliSessionOnResume: true, - resumeAt: resumeCheckpointId, - onForkSuccessorPersisted: (sessionId) => { - retryableSessionId = sessionId; - }, - }), - ); - } catch (forkError) { - const deliveredForkFailure = await finishDeliveredFailure(forkError); - if (deliveredForkFailure) { - return deliveredForkFailure; - } - recoveryError = isUnsupportedCliResumeAtError( - forkError, - context.preparedBackend.backend.resumeAtArg, - ) - ? err - : forkError; - } - } - if ( - isFailoverError(recoveryError) && - shouldRetryFreshCliSessionAfterFailover({ - error: recoveryError, - hasHistoryPrompt: Boolean(context.openClawHistoryPrompt), - }) && - retryableSessionId && - params.sessionKey - ) { - try { - const retryTimeoutMs = params.timeoutMs - (Date.now() - context.started); - if (retryTimeoutMs <= 0) { - throw recoveryError; - } - if (params.onBeforeFreshCliSessionRetry) { - const clearedStaleBinding = await params.onBeforeFreshCliSessionRetry({ - provider: params.provider, - reason: recoveryError.reason, - sessionId: retryableSessionId, - }); - if (!clearedStaleBinding) { - throw recoveryError; - } - } - cliBackendLog.warn( - `cli session recovery retry: provider=${params.provider} reason=${recoveryError.reason} sessionKey=${params.sessionKey}`, - ); - return await finishCliAttempt( - await executeCliAttempt(undefined, { - timeoutMs: retryTimeoutMs, - forkCliSessionOnResume: false, - }), - ); - } catch (retryErr) { - const deliveredRetryFailure = await finishDeliveredFailure(retryErr); - if (deliveredRetryFailure) { - return deliveredRetryFailure; - } - const retryMessage = formatErrorMessage(retryErr); - await runCliAgentEndHook(params, { - event: buildFailedAgentEndEvent(retryMessage), - ctx: hookContext, - hookRunner, - }); - throw retryErr; - } - } - } - if (isFailoverError(recoveryError)) { + return await runCliRecovery({ + context, + executeAttempt: executeCliAttempt, + finishAttempt: finishCliAttempt, + finishDeliveredFailure, + onTerminalFailure: async (error) => { await runCliAgentEndHook(params, { - event: buildFailedAgentEndEvent(formatErrorMessage(recoveryError)), + event: buildFailedAgentEndEvent(formatErrorMessage(error)), ctx: hookContext, hookRunner, }); - throw recoveryError; - } - const message = formatErrorMessage(recoveryError); - await runCliAgentEndHook(params, { - event: buildFailedAgentEndEvent(message), - ctx: hookContext, - hookRunner, - }); - throw recoveryError; - } + }, + }); }; let runResult: EmbeddedAgentRunResult | undefined; @@ -1780,28 +680,19 @@ export async function runPreparedCliAgent( runFailed = true; runError = error; } + let cleanupError: Error | undefined; try { await context.preparedBackend.cleanup?.(); - } catch (cleanupError) { - if (!deliveredMessagingSideEffect) { - if (runFailed) { - cliBackendLog.warn( - `CLI run also failed before backend cleanup: ${formatErrorMessage(runError)}`, - ); - } - diagnosticLifecycle?.setPhase("cleanup"); - throw cleanupError; - } - cliBackendLog.warn( - `CLI backend cleanup failed after confirmed message delivery: ${formatErrorMessage(cleanupError)}`, - ); + } catch (error) { + cleanupError = error as Error; } - if (runFailed) { - throw coerceToFailoverError(runError, cliFailoverContext) ?? runError; - } - if (!runResult) { - throw new Error("CLI run completed without a result"); - } - return runResult; + return settleCliBackendOutcome({ + runResult, + runError, + runFailed, + cleanupError, + deliveredMessagingSideEffect, + diagnosticLifecycle, + failoverContext: cliFailoverContext, + }); } -/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */ diff --git a/src/agents/cli-runner/cli-run-recovery.ts b/src/agents/cli-runner/cli-run-recovery.ts new file mode 100644 index 000000000000..956cbca8252f --- /dev/null +++ b/src/agents/cli-runner/cli-run-recovery.ts @@ -0,0 +1,207 @@ +import { formatErrorMessage } from "../../infra/errors.js"; +import type { EmbeddedAgentRunResult } from "../embedded-agent-runner.js"; +import { type FailoverError, isFailoverError } from "../failover-error.js"; +import { createCliFailoverError } from "./exit-error.js"; +import { cliBackendLog } from "./log.js"; +import type { CliReusableSession, PreparedCliRunContext } from "./types.js"; + +export type CliRecoveryOptions = { + timeoutMs?: number; + forkCliSessionOnResume?: boolean; + resumeAt?: string; + onForkSuccessorPersisted?: (sessionId: string) => void; +}; + +export function resolveCliSessionId(reusableCliSession: CliReusableSession): string | undefined { + return reusableCliSession.mode === "reuse" || reusableCliSession.mode === "reuse-with-drift" + ? reusableCliSession.sessionId + : undefined; +} + +function shouldRetryFreshCliSessionAfterFailover(params: { + error: FailoverError; + hasHistoryPrompt: boolean; +}): boolean { + if (!params.hasHistoryPrompt) { + return false; + } + switch (params.error.reason) { + case "session_expired": + return true; + case "unknown": + return params.error.code === "cli_unknown_empty_failure"; + case "empty_response": + return params.error.code === "cli_unknown_empty_failure"; + case "format": + return params.error.code === "cli_synthetic_no_response"; + case "timeout": + return params.error.code === "cli_no_output_timeout"; + case "context_overflow": + return params.error.code === "cli_context_overflow"; + default: + return false; + } +} + +function shouldRetryForkedCliSessionAfterFailover(error: FailoverError): boolean { + return error.reason === "timeout" && error.code === "cli_no_output_timeout"; +} + +function isUnsupportedCliResumeAtError(error: unknown, resumeAtArg: string): boolean { + const message = formatErrorMessage(error).toLowerCase(); + return ( + message.includes(resumeAtArg.toLowerCase()) && + /\b(?:unknown|unexpected|unrecognized)\b|\bnot\s+recognized\b/.test(message) + ); +} + +export async function runCliRecovery(params: { + context: PreparedCliRunContext; + executeAttempt: (cliSessionIdToUse?: string, options?: CliRecoveryOptions) => Promise; + finishAttempt: ( + attempt: TAttempt, + fallbackCliSessionId?: string, + ) => Promise; + finishDeliveredFailure: (error: unknown) => Promise; + onTerminalFailure: (error: unknown) => Promise; +}): Promise { + const { context } = params; + const runParams = context.params; + const reusableCliSessionId = resolveCliSessionId(context.reusableCliSession); + const resumeCheckpointId = runParams.cliSessionBinding?.resumeCheckpointId; + let retryableSessionId = reusableCliSessionId; + try { + return await params.finishAttempt( + await params.executeAttempt( + reusableCliSessionId, + runParams.forkCliSessionOnResume + ? { + onForkSuccessorPersisted: (sessionId) => { + retryableSessionId = sessionId; + }, + } + : undefined, + ), + reusableCliSessionId, + ); + } catch (err) { + const deliveredFailure = await params.finishDeliveredFailure(err); + if (deliveredFailure) { + return deliveredFailure; + } + let recoveryError = err; + if ( + runParams.forkCliSessionOnResume && + resumeCheckpointId && + context.preparedBackend.backend.resumeAtArg && + isUnsupportedCliResumeAtError(err, context.preparedBackend.backend.resumeAtArg) + ) { + recoveryError = createCliFailoverError( + "CLI backend cannot resume from the stored checkpoint.", + "session_expired", + { + provider: runParams.provider, + model: context.modelId, + sessionId: runParams.sessionId, + lane: runParams.lane, + }, + { cause: err }, + ); + } + if (isFailoverError(recoveryError)) { + if ( + !runParams.forkCliSessionOnResume && + shouldRetryForkedCliSessionAfterFailover(recoveryError) && + retryableSessionId && + resumeCheckpointId && + runParams.sessionKey && + context.preparedBackend.backend.forkArg && + context.preparedBackend.backend.resumeAtArg && + runParams.onBeforeForkedCliSessionRetry + ) { + try { + const retryTimeoutMs = runParams.timeoutMs - (Date.now() - context.started); + if (retryTimeoutMs <= 0) { + throw recoveryError; + } + const forkPrepared = await runParams.onBeforeForkedCliSessionRetry({ + provider: runParams.provider, + reason: recoveryError.reason, + sessionId: retryableSessionId, + }); + if (!forkPrepared) { + throw recoveryError; + } + cliBackendLog.warn( + `cli session recovery fork: provider=${runParams.provider} reason=${recoveryError.reason} sessionKey=${runParams.sessionKey}`, + ); + return await params.finishAttempt( + await params.executeAttempt(retryableSessionId, { + timeoutMs: retryTimeoutMs, + forkCliSessionOnResume: true, + resumeAt: resumeCheckpointId, + onForkSuccessorPersisted: (sessionId) => { + retryableSessionId = sessionId; + }, + }), + ); + } catch (forkError) { + const deliveredForkFailure = await params.finishDeliveredFailure(forkError); + if (deliveredForkFailure) { + return deliveredForkFailure; + } + recoveryError = isUnsupportedCliResumeAtError( + forkError, + context.preparedBackend.backend.resumeAtArg, + ) + ? err + : forkError; + } + } + if ( + isFailoverError(recoveryError) && + shouldRetryFreshCliSessionAfterFailover({ + error: recoveryError, + hasHistoryPrompt: Boolean(context.openClawHistoryPrompt), + }) && + retryableSessionId && + runParams.sessionKey + ) { + try { + const retryTimeoutMs = runParams.timeoutMs - (Date.now() - context.started); + if (retryTimeoutMs <= 0) { + throw recoveryError; + } + if (runParams.onBeforeFreshCliSessionRetry) { + const clearedStaleBinding = await runParams.onBeforeFreshCliSessionRetry({ + provider: runParams.provider, + reason: recoveryError.reason, + sessionId: retryableSessionId, + }); + if (!clearedStaleBinding) { + throw recoveryError; + } + } + cliBackendLog.warn( + `cli session recovery retry: provider=${runParams.provider} reason=${recoveryError.reason} sessionKey=${runParams.sessionKey}`, + ); + return await params.finishAttempt( + await params.executeAttempt(undefined, { + timeoutMs: retryTimeoutMs, + forkCliSessionOnResume: false, + }), + ); + } catch (retryErr) { + const deliveredRetryFailure = await params.finishDeliveredFailure(retryErr); + if (deliveredRetryFailure) { + return deliveredRetryFailure; + } + await params.onTerminalFailure(retryErr); + throw retryErr; + } + } + } + await params.onTerminalFailure(recoveryError); + throw recoveryError; + } +} diff --git a/src/agents/cli-runner.binding-flush.test.ts b/src/agents/cli-runner/cli-run-settlement.test.ts similarity index 99% rename from src/agents/cli-runner.binding-flush.test.ts rename to src/agents/cli-runner/cli-run-settlement.test.ts index a9efedb0145e..9e5fee24d800 100644 --- a/src/agents/cli-runner.binding-flush.test.ts +++ b/src/agents/cli-runner/cli-run-settlement.test.ts @@ -4,7 +4,7 @@ import { isCliBindingFlushed, restoreCliRunnerTestDeps, setCliRunnerTestDeps, -} from "./cli-runner.js"; +} from "../cli-runner.js"; describe("isCliBindingFlushed", () => { const workspaceDir = "/tmp/openclaw-workspace"; diff --git a/src/agents/cli-runner/cli-run-settlement.ts b/src/agents/cli-runner/cli-run-settlement.ts new file mode 100644 index 000000000000..318ca626dbdc --- /dev/null +++ b/src/agents/cli-runner/cli-run-settlement.ts @@ -0,0 +1,657 @@ +import { setReplyPayloadMetadata, type ReplyPayload } from "../../auto-reply/reply-payload.js"; +import { SILENT_REPLY_TOKEN } from "../../auto-reply/tokens.js"; +import { formatErrorMessage } from "../../infra/errors.js"; +import { createSubsystemLogger } from "../../logging/subsystem.js"; +import { + externalCliDiscoveryForProviderAuth, + loadAuthProfileStoreForRuntime, + markAuthProfileFailure, + markAuthProfileSuccess, + type AuthProfileStore, +} from "../auth-profiles.js"; +import { + resolveCliRuntimeArtifactFingerprint, + resolveCliRuntimeOwnerFingerprint, +} from "../cli-auth-epoch.js"; +import type { CliOutput } from "../cli-output-contracts.js"; +import { claudeCliSessionTranscriptHasContent as claudeCliSessionTranscriptHasContentImpl } from "../command/attempt-execution.helpers.js"; +import type { EmbeddedAgentRunResult } from "../embedded-agent-runner.js"; +import { resolveExplicitFinalSourceReplyDeliveryEvidence } from "../embedded-agent-runner/delivery-evidence.js"; +import { resolveAuthProfileFailureReason } from "../embedded-agent-runner/run/auth-profile-failure-policy.js"; +import { buildEmbeddedRunPayloads } from "../embedded-agent-runner/run/payloads.js"; +import { coerceToFailoverError, isFailoverError } from "../failover-error.js"; +import { CliAuthProfilePreparationError } from "./auth-profile-preparation-error.js"; +import { hashCliReseedPrompt } from "./reseed-envelope.js"; +import type { ClaudeCliRunDiagnosticLifecycle } from "./run-diagnostics.js"; +import type { PreparedCliRunContext, RunCliAgentParams } from "./types.js"; + +const log = createSubsystemLogger("agents/cli-runner"); + +export const cliRunSettlementDeps = { + claudeCliSessionTranscriptHasContent: claudeCliSessionTranscriptHasContentImpl, + delay: async (delayMs: number) => { + await new Promise((resolve) => { + setTimeout(resolve, delayMs); + }); + }, + loadAuthProfileStoreForRuntime, + markAuthProfileFailure, + markAuthProfileSuccess, +}; + +async function settleCliAuthProfile(params: { + store: AuthProfileStore; + profileId: string; + provider: string; + agentDir?: string; + terminal: + | { outcome: "success" } + | { + outcome: "failure"; + error: unknown; + config?: RunCliAgentParams["config"]; + runId: string; + modelId?: string; + }; +}): Promise { + try { + if (params.terminal.outcome === "success") { + await cliRunSettlementDeps.markAuthProfileSuccess({ + store: params.store, + profileId: params.profileId, + provider: params.provider, + agentDir: params.agentDir, + }); + return; + } + const error = params.terminal.error; + const reason = resolveAuthProfileFailureReason({ + failoverReason: isFailoverError(error) ? error.reason : null, + providerStarted: + isFailoverError(error) && error.reason === "timeout" + ? error.cliTimeout?.observedActivity + : undefined, + }); + if (reason) { + await cliRunSettlementDeps.markAuthProfileFailure({ + store: params.store, + profileId: params.profileId, + reason, + cfg: params.terminal.config, + agentDir: params.agentDir, + runId: params.terminal.runId, + modelId: params.terminal.modelId, + }); + } + } catch (error) { + log.warn( + `CLI auth-profile ${params.terminal.outcome} settlement failed: ${formatErrorMessage(error)}`, + ); + } +} + +export function isClaudeCliBackend(provider: string): boolean { + return provider.trim().toLowerCase() === "claude-cli"; +} + +export async function assertCliRuntimeBinding(context: PreparedCliRunContext): Promise { + if (!context.runtimeArtifactFingerprint) { + return; + } + const currentArtifact = await resolveCliRuntimeArtifactFingerprint({ + provider: context.params.provider, + config: context.params.config ?? context.contextEngineConfig, + agentId: context.params.agentId, + runtimeArtifactId: context.backendResolved.id, + }); + if (currentArtifact !== context.runtimeArtifactFingerprint) { + throw new Error("CLI executable/package artifact changed during successful inference"); + } + if (!context.runtimeOwnerFingerprint) { + return; + } + const currentOwner = await resolveCliRuntimeOwnerFingerprint({ + provider: context.params.provider, + config: context.params.config ?? context.contextEngineConfig, + ...(context.agentDir ? { agentDir: context.agentDir } : {}), + agentId: context.params.agentId, + runtimeOwnerId: context.backendResolved.id, + ...(context.effectiveAuthProfileId ? { authProfileId: context.effectiveAuthProfileId } : {}), + ...(context.authBindingSkipsLocalCredential ? { skipLocalCredential: true } : {}), + runtimeArtifactFingerprint: currentArtifact, + }); + if (currentOwner !== context.runtimeOwnerFingerprint) { + throw new Error("CLI runtime owner changed during successful inference"); + } +} + +export async function settleCliPreparationError( + error: unknown, + params: RunCliAgentParams, +): Promise { + if (!(error instanceof CliAuthProfilePreparationError)) { + return; + } + const store = cliRunSettlementDeps.loadAuthProfileStoreForRuntime(error.agentDir, { + externalCli: externalCliDiscoveryForProviderAuth({ + cfg: params.config, + provider: error.provider, + profileId: error.profileId, + }), + }); + await settleCliAuthProfile({ + store, + profileId: error.profileId, + provider: error.provider, + agentDir: error.agentDir, + terminal: { + outcome: "failure", + error, + config: params.config, + runId: params.runId, + modelId: params.model, + }, + }); +} + +export async function settlePreparedCliRun(params: { + context: PreparedCliRunContext; + diagnosticLifecycle?: ClaudeCliRunDiagnosticLifecycle; + run: () => Promise; +}): Promise { + const { context, diagnosticLifecycle, run } = params; + const runParams = context.params; + let result: EmbeddedAgentRunResult | undefined; + let runError: unknown; + try { + result = await run(); + } catch (error) { + runError = error; + } + const terminalRunError = runError; + let cleanupError: unknown; + const recordCleanupError = (error: unknown) => { + cleanupError ??= error; + }; + if (runParams.cleanupCliLiveSessionOnRunEnd === true) { + try { + const { closeClaudeSession } = await import("./claude-live-registry.js"); + await closeClaudeSession(context, "restart"); + } catch (error) { + recordCleanupError(error); + } + } + if (runParams.cleanupBundleMcpOnRunEnd === true) { + // The run's session ID is immutable; its session key can already belong to + // a newer run. Never retire the newer runtime or close the shared listener. + try { + const { retireSessionMcpRuntime } = await import("../agent-bundle-mcp-tools.js"); + await retireSessionMcpRuntime({ + sessionId: runParams.sessionId, + reason: "cli-run-end", + onError: recordCleanupError, + }); + } catch (error) { + recordCleanupError(error); + } + } + if (cleanupError) { + if (runError || result?.didSendViaMessagingTool === true) { + log.warn(`cli run cleanup failed after completion: ${formatErrorMessage(cleanupError)}`); + } else { + diagnosticLifecycle?.setPhase("cleanup"); + runError = + cleanupError instanceof Error ? cleanupError : new Error(formatErrorMessage(cleanupError)); + } + } + // Settle only after backend recovery is exhausted. Recording inside an + // attempt would quarantine a healthy profile for a recovered session fault. + if (context.effectiveAuthProfileId && context.authProfileStore) { + const profileId = context.effectiveAuthProfileId; + const authProfileStore = context.authProfileStore; + if (terminalRunError) { + await settleCliAuthProfile({ + store: authProfileStore, + profileId, + provider: authProfileStore.profiles[profileId]?.provider ?? runParams.provider, + agentDir: context.agentDir, + terminal: { + outcome: "failure", + error: terminalRunError, + config: runParams.config, + runId: runParams.runId, + modelId: context.modelId, + }, + }); + } else if (result?.meta.executionTrace?.attempts?.at(-1)?.result === "success") { + const provider = authProfileStore.profiles[profileId]?.provider ?? runParams.provider; + await settleCliAuthProfile({ + store: authProfileStore, + profileId, + provider, + agentDir: context.agentDir, + terminal: { outcome: "success" }, + }); + } + } + if (runError) { + throw runError instanceof Error ? runError : new Error(formatErrorMessage(runError)); + } + return result as EmbeddedAgentRunResult; +} + +export function resolveCliSourceReplyMirror(params: { + evidence: Pick< + CliOutput, + | "didSendViaMessagingTool" + | "didDeliverSourceReplyViaMessageTool" + | "messagingToolSentTargets" + | "messagingToolSourceReplyPayloads" + >; + runParams: RunCliAgentParams; + modelId: string; +}): { payloads: ReplyPayload[]; delivered: boolean; visibleText?: string } { + const { evidence, modelId, runParams } = params; + const payloads = buildEmbeddedRunPayloads({ + assistantTexts: [], + lastAssistant: undefined, + sessionKey: runParams.sessionKey ?? "", + provider: runParams.provider, + model: modelId, + didSendViaMessagingTool: evidence.didSendViaMessagingTool, + didDeliverSourceReplyViaMessageTool: evidence.didDeliverSourceReplyViaMessageTool, + messagingToolSentTargets: evidence.messagingToolSentTargets, + messagingToolSourceReplyPayloads: evidence.messagingToolSourceReplyPayloads, + sourceReplyDeliveryMode: runParams.sourceReplyDeliveryMode, + agentId: runParams.agentId, + runId: runParams.runId, + }); + const delivered = + payloads.length > 0 || + (runParams.sourceReplyDeliveryMode === "message_tool_only" && + evidence.didDeliverSourceReplyViaMessageTool === true); + const visibleText = + payloads + .map((payload) => payload.text?.trim() ?? "") + .filter(Boolean) + .join("\n\n") || undefined; + return { payloads, delivered, visibleText }; +} + +export function buildBlockedCliRunResult(params: { + message: string; + context: PreparedCliRunContext; + preparedContextAgentMeta: { contextTokens?: number }; + sessionBindingDisabled: boolean; +}): EmbeddedAgentRunResult { + const { context, message, preparedContextAgentMeta, sessionBindingDisabled } = params; + const runParams = context.params; + return { + payloads: [{ text: message, isError: true }], + meta: { + durationMs: Date.now() - context.started, + finalAssistantVisibleText: message, + finalAssistantRawText: message, + livenessState: "blocked", + error: { + kind: "hook_block", + message, + }, + systemPromptReport: context.systemPromptReport, + executionTrace: { + winnerProvider: runParams.provider, + winnerModel: context.modelId, + attempts: [ + { + provider: runParams.provider, + model: context.modelId, + result: "error", + reason: "before_agent_run blocked the run", + }, + ], + fallbackUsed: false, + runner: "cli", + }, + requestShaping: { + ...(runParams.thinkLevel ? { thinking: runParams.thinkLevel } : {}), + ...(context.effectiveAuthProfileId ? { authMode: "auth-profile" } : {}), + }, + completion: { + finishReason: "blocked", + stopReason: "blocked", + refusal: true, + }, + agentMeta: { + sessionId: runParams.sessionId ?? "", + provider: runParams.provider, + model: context.modelId, + ...preparedContextAgentMeta, + ...(sessionBindingDisabled ? { clearCliSessionBinding: true } : {}), + }, + }, + }; +} + +export function buildCliDeliveredFailure(params: { + error: unknown; + evidence: NonNullable< + ReturnType + >; + context: PreparedCliRunContext; + preparedContextAgentMeta: { contextTokens?: number }; + sessionBindingDisabled: boolean; + reusableCliSessionId?: string; +}): EmbeddedAgentRunResult { + const { + context, + error, + evidence, + preparedContextAgentMeta, + reusableCliSessionId, + sessionBindingDisabled, + } = params; + const runParams = context.params; + const message = formatErrorMessage(error); + const { payloads } = resolveCliSourceReplyMirror({ + evidence, + runParams, + modelId: context.modelId, + }); + const visiblePayloads = + payloads.length > 0 + ? payloads + : resolveExplicitFinalSourceReplyDeliveryEvidence(evidence) === false + ? [{ text: "The reply stopped after sending progress. Please try again.", isError: true }] + : undefined; + return { + ...(visiblePayloads ? { payloads: visiblePayloads } : {}), + meta: { + durationMs: Date.now() - context.started, + systemPromptReport: context.systemPromptReport, + stopReason: "error", + executionTrace: { + winnerProvider: runParams.provider, + winnerModel: context.modelId, + attempts: [ + { + provider: runParams.provider, + model: context.modelId, + result: "error", + reason: message, + }, + ], + fallbackUsed: false, + runner: "cli", + }, + requestShaping: { + ...(runParams.thinkLevel ? { thinking: runParams.thinkLevel } : {}), + ...(context.effectiveAuthProfileId ? { authMode: "auth-profile" } : {}), + }, + completion: { + finishReason: "error", + stopReason: "error", + refusal: false, + }, + agentMeta: { + sessionId: "", + provider: runParams.provider, + model: context.modelId, + ...preparedContextAgentMeta, + ...(sessionBindingDisabled || reusableCliSessionId ? { clearCliSessionBinding: true } : {}), + }, + }, + didSendViaMessagingTool: true, + ...(evidence.didDeliverSourceReplyViaMessageTool + ? { didDeliverSourceReplyViaMessageTool: true } + : {}), + ...(evidence.messagingToolSentTexts?.length + ? { messagingToolSentTexts: evidence.messagingToolSentTexts } + : {}), + ...(evidence.messagingToolSentMediaUrls?.length + ? { messagingToolSentMediaUrls: evidence.messagingToolSentMediaUrls } + : {}), + ...(evidence.messagingToolSentTargets?.length + ? { messagingToolSentTargets: evidence.messagingToolSentTargets } + : {}), + ...(evidence.messagingToolSourceReplyPayloads?.length + ? { messagingToolSourceReplyPayloads: evidence.messagingToolSourceReplyPayloads } + : {}), + }; +} + +export function buildCliRunResult(params: { + context: PreparedCliRunContext; + output: CliOutput; + effectiveCliSessionId?: string; + bindingFlushOk?: boolean; + assistantTranscriptOwned?: boolean; + usedHistoryPrompt: boolean; + userTurnHandled: boolean; + sessionBindingDisabled: boolean; + preparedContextAgentMeta: { contextTokens?: number }; +}): EmbeddedAgentRunResult { + const { + assistantTranscriptOwned, + bindingFlushOk, + context, + effectiveCliSessionId, + output, + preparedContextAgentMeta, + sessionBindingDisabled, + usedHistoryPrompt, + userTurnHandled, + } = params; + const runParams = context.params; + const text = output.text?.trim(); + const rawText = output.rawText?.trim(); + const sourceReplyMirror = resolveCliSourceReplyMirror({ + evidence: output, + runParams, + modelId: context.modelId, + }); + const finalAssistantVisibleText = sourceReplyMirror.delivered + ? sourceReplyMirror.visibleText + : text; + const payloads = + sourceReplyMirror.payloads.length > 0 + ? sourceReplyMirror.payloads + : sourceReplyMirror.delivered + ? undefined + : text + ? [ + assistantTranscriptOwned + ? setReplyPayloadMetadata({ text }, { assistantTranscriptOwned: true }) + : { text }, + ] + : runParams.allowEmptyAssistantReplyAsSilent === true + ? [{ text: SILENT_REPLY_TOKEN }] + : undefined; + const unflushedCliSessionId = + !sessionBindingDisabled && effectiveCliSessionId && bindingFlushOk === false + ? effectiveCliSessionId + : undefined; + const persistedCliSessionId = sessionBindingDisabled + ? undefined + : unflushedCliSessionId + ? undefined + : effectiveCliSessionId; + const createdReseedReceipt = + persistedCliSessionId && + usedHistoryPrompt && + isClaudeCliBackend(runParams.provider) && + output.finalPromptText !== undefined && + userTurnHandled && + runParams.sessionId + ? { + version: 1 as const, + promptHash: hashCliReseedPrompt(output.finalPromptText), + localSessionId: runParams.sessionId, + userTurnDisposition: runParams.userTurnTranscriptRecorder?.hasPersisted() + ? ("persisted" as const) + : ("omitted" as const), + } + : undefined; + const preservedReseedReceipt = + runParams.cliSessionBinding && persistedCliSessionId === runParams.cliSessionBinding.sessionId + ? runParams.cliSessionBinding.reseedReceipt + : undefined; + const reseedReceipt = createdReseedReceipt ?? preservedReseedReceipt; + const agentSessionId = sessionBindingDisabled + ? (runParams.sessionId ?? "") + : unflushedCliSessionId + ? "" + : (effectiveCliSessionId ?? runParams.sessionId ?? ""); + const yielded = output.yielded === true; + const stopReason = yielded ? "end_turn" : "completed"; + + runParams.onSuccessfulAuthBinding?.({ + ...(context.effectiveAuthProfileId ? { authProfileId: context.effectiveAuthProfileId } : {}), + ...(context.authBindingFingerprint ? { authFingerprint: context.authBindingFingerprint } : {}), + ...(!context.authBindingFingerprint && context.runtimeOwnerFingerprint + ? { + runtimeOwnerFingerprint: context.runtimeOwnerFingerprint, + runtimeOwnerKind: "cli-runtime" as const, + runtimeOwnerId: context.backendResolved.id, + } + : {}), + ...(context.runtimeArtifactFingerprint + ? { + runtimeArtifactFingerprint: context.runtimeArtifactFingerprint, + runtimeArtifactId: context.backendResolved.id, + } + : {}), + ...(context.authBindingSkipsLocalCredential ? { skipLocalCredential: true } : {}), + }); + + return { + payloads, + meta: { + durationMs: Date.now() - context.started, + ...(output.finalPromptText ? { finalPromptText: output.finalPromptText } : {}), + ...(finalAssistantVisibleText || rawText + ? { + ...(finalAssistantVisibleText ? { finalAssistantVisibleText } : {}), + ...(rawText ? { finalAssistantRawText: rawText } : {}), + } + : {}), + systemPromptReport: context.systemPromptReport, + ...(yielded ? { yielded: true, livenessState: "paused" as const, stopReason } : {}), + executionTrace: { + winnerProvider: runParams.provider, + winnerModel: context.modelId, + attempts: [{ provider: runParams.provider, model: context.modelId, result: "success" }], + fallbackUsed: false, + runner: "cli", + }, + requestShaping: { + ...(runParams.thinkLevel ? { thinking: runParams.thinkLevel } : {}), + ...(context.effectiveAuthProfileId ? { authMode: "auth-profile" } : {}), + }, + completion: { + finishReason: yielded ? "end_turn" : "stop", + stopReason, + refusal: false, + }, + ...(output.toolSummary ? { toolSummary: output.toolSummary } : {}), + agentMeta: { + sessionId: agentSessionId, + provider: runParams.provider, + model: context.modelId, + ...preparedContextAgentMeta, + usage: output.usage, + ...(output.usage ? { lastCallUsage: output.usage } : {}), + ...(output.diagnosticUsage ? { diagnosticUsage: output.diagnosticUsage } : {}), + ...(persistedCliSessionId + ? { + cliSessionBinding: { + sessionId: persistedCliSessionId, + ...(context.effectiveAuthProfileId + ? { authProfileId: context.effectiveAuthProfileId } + : {}), + ...(output.resumeCheckpointId + ? { resumeCheckpointId: output.resumeCheckpointId } + : {}), + ...(context.authEpoch ? { authEpoch: context.authEpoch } : {}), + authEpochVersion: context.authEpochVersion, + ...(context.extraSystemPromptHash + ? { extraSystemPromptHash: context.extraSystemPromptHash } + : {}), + ...(context.messageToolPolicyHash + ? { messageToolPolicyHash: context.messageToolPolicyHash } + : {}), + ...(context.promptToolNamesHash + ? { promptToolNamesHash: context.promptToolNamesHash } + : {}), + ...(context.cwdHash ? { cwdHash: context.cwdHash } : {}), + ...(context.preparedBackend.mcpConfigHash + ? { mcpConfigHash: context.preparedBackend.mcpConfigHash } + : {}), + ...(context.preparedBackend.mcpResumeHash + ? { mcpResumeHash: context.preparedBackend.mcpResumeHash } + : {}), + ...(reseedReceipt ? { reseedReceipt } : {}), + }, + } + : {}), + ...(sessionBindingDisabled || unflushedCliSessionId + ? { clearCliSessionBinding: true } + : {}), + }, + }, + ...(output.didSendViaMessagingTool ? { didSendViaMessagingTool: true } : {}), + ...(output.didDeliverSourceReplyViaMessageTool + ? { didDeliverSourceReplyViaMessageTool: true } + : {}), + ...(output.messagingToolSentTexts?.length + ? { messagingToolSentTexts: output.messagingToolSentTexts } + : {}), + ...(output.messagingToolSentMediaUrls?.length + ? { messagingToolSentMediaUrls: output.messagingToolSentMediaUrls } + : {}), + ...(output.messagingToolSentTargets?.length + ? { messagingToolSentTargets: output.messagingToolSentTargets } + : {}), + ...(output.messagingToolSourceReplyPayloads?.length + ? { messagingToolSourceReplyPayloads: output.messagingToolSourceReplyPayloads } + : {}), + }; +} + +export function settleCliBackendOutcome(params: { + runResult: EmbeddedAgentRunResult | undefined; + runError: unknown; + runFailed: boolean; + cleanupError: Error | undefined; + deliveredMessagingSideEffect: boolean; + diagnosticLifecycle?: ClaudeCliRunDiagnosticLifecycle; + failoverContext: { provider: string; model: string; sessionId: string; lane?: string }; +}): EmbeddedAgentRunResult { + const { + cleanupError, + deliveredMessagingSideEffect, + diagnosticLifecycle, + failoverContext, + runError, + runFailed, + runResult, + } = params; + if (cleanupError) { + if (!deliveredMessagingSideEffect) { + if (runFailed) { + log.warn(`CLI run also failed before backend cleanup: ${formatErrorMessage(runError)}`); + } + diagnosticLifecycle?.setPhase("cleanup"); + throw cleanupError; + } + log.warn( + `CLI backend cleanup failed after confirmed message delivery: ${formatErrorMessage(cleanupError)}`, + ); + } + if (runFailed) { + throw coerceToFailoverError(runError, failoverContext) ?? runError; + } + if (!runResult) { + throw new Error("CLI run completed without a result"); + } + return runResult; +} diff --git a/src/agents/cli-runner/cli-run-transcript.ts b/src/agents/cli-runner/cli-run-transcript.ts new file mode 100644 index 000000000000..944e1615785f --- /dev/null +++ b/src/agents/cli-runner/cli-run-transcript.ts @@ -0,0 +1,404 @@ +import { resolveSessionStorePathCore } from "../../config/sessions/paths.js"; +import { patchSessionEntryCore } from "../../config/sessions/session-accessor.js"; +import { appendExactAssistantMessageToSessionTranscript } from "../../config/sessions/transcript.js"; +import { buildGenericCliContextEngineHostSupport } from "../../context-engine/host-compat.js"; +import { formatErrorMessage } from "../../infra/errors.js"; +import { createSubsystemLogger } from "../../logging/subsystem.js"; +import { resolveAgentIdFromSessionKey } from "../../routing/session-key.js"; +import { isHeartbeatLifecycleRunKind } from "../bootstrap-mode.js"; +import type { CliOutput } from "../cli-output-contracts.js"; +import { + awaitAgentEndSideEffects, + runAgentEndSideEffects, +} from "../harness/agent-end-side-effects.js"; +import { + finalizeHarnessContextEngineTurn, + runHarnessContextEngineMaintenance, +} from "../harness/context-engine-lifecycle.js"; +import { runAgentHarnessBeforeMessageWriteHook } from "../harness/hook-helpers.js"; +import type { AgentMessage } from "../runtime/index.js"; +import { SessionManager } from "../sessions/session-manager.js"; +import { buildAssistantMessage, buildUsageWithNoCost } from "../stream-message-shared.js"; +import type { PreparedCliRunContext, RunCliAgentParams } from "./types.js"; + +const log = createSubsystemLogger("agents/cli-runner"); + +export function buildCliHookUserMessage(prompt: string): unknown { + return { + role: "user", + content: prompt, + timestamp: Date.now(), + }; +} + +export function buildCliHookAssistantMessage(params: { + text: string; + provider: string; + model: string; + usage?: { + input?: number; + output?: number; + cacheRead?: number; + cacheWrite?: number; + total?: number; + }; +}): unknown { + return { + role: "assistant", + content: [{ type: "text", text: params.text }], + api: "responses", + provider: params.provider, + model: params.model, + ...(params.usage ? { usage: params.usage } : {}), + stopReason: "stop", + timestamp: Date.now(), + }; +} + +function isAgentMessage(value: unknown): value is AgentMessage { + return Boolean(value && typeof value === "object" && "role" in value); +} + +function buildCliContextEngineUserMessage(prompt: string): AgentMessage { + return { + role: "user", + content: prompt, + timestamp: Date.now(), + } as AgentMessage; +} + +function buildCliContextEngineAssistantMessage(params: { + text: string; + provider: string; + model: string; + usage?: { + input?: number; + output?: number; + cacheRead?: number; + cacheWrite?: number; + total?: number; + }; +}): AgentMessage { + return buildCliHookAssistantMessage(params) as AgentMessage; +} + +type CliAgentEndHookParams = Parameters[0]; + +function shouldAwaitCliAgentEndHook(params: RunCliAgentParams): boolean { + return !params.messageChannel && !params.messageProvider; +} + +export async function runCliAgentEndHook( + params: RunCliAgentParams, + hookParams: CliAgentEndHookParams, +): Promise { + if (shouldAwaitCliAgentEndHook(params)) { + await awaitAgentEndSideEffects(hookParams); + return; + } + runAgentEndSideEffects(hookParams); +} + +export async function persistApprovedCliUserTurnTranscript( + params: RunCliAgentParams, +): Promise { + const recorder = params.userTurnTranscriptRecorder; + const reusingPersistedTurn = params.suppressNextUserMessagePersistence === true; + if (!recorder || (reusingPersistedTurn && !recorder.hasPersisted())) { + return recorder?.isBlocked() === true; + } + + const persisted = await recorder.persistApproved({ + cwd: params.cwd ?? params.workspaceDir, + }); + if (!persisted && !recorder.hasPersisted() && (await recorder.resolveMessage())) { + // A prepared user row can be rejected by before_message_write. Preserve + // that terminal decision so outer transcript mirrors do not retry it. + recorder.markBlocked(); + } + if (persisted && !reusingPersistedTurn) { + try { + const notification = params.onUserMessagePersisted?.(persisted.message); + if (notification) { + void Promise.resolve(notification).catch((error: unknown) => { + log.warn(`CLI user turn persistence notification failed: ${formatErrorMessage(error)}`); + }); + } + } catch (error) { + log.warn(`CLI user turn persistence notification failed: ${formatErrorMessage(error)}`); + } + } + return persisted !== undefined || recorder.hasPersisted() || recorder.isBlocked(); +} + +export async function persistCliAssistantTranscript(params: { + runParams: RunCliAgentParams; + text: string; + modelId: string; + usage?: { + input?: number; + output?: number; + cacheRead?: number; + cacheWrite?: number; + total?: number; + }; +}): Promise<{ + owned: boolean; + terminalAnchor?: import("../../config/sessions/session-accessor.js").TranscriptEntryAnchor; +}> { + const { runParams } = params; + if (runParams.currentInboundEventKind === "room_event") { + const admission = runParams.userTurnTranscriptRecorder?.getAdmissionReceipt(); + return { + owned: true, + ...(admission ? { terminalAnchor: admission } : {}), + }; + } + if (!params.text) { + const admission = runParams.userTurnTranscriptRecorder?.getAdmissionReceipt(); + return { + owned: false, + ...(admission ? { terminalAnchor: admission } : {}), + }; + } + if (!runParams.persistAssistantTranscript || !runParams.sessionKey) { + return { owned: false }; + } + try { + const result = await appendExactAssistantMessageToSessionTranscript({ + sessionKey: runParams.sessionKey, + agentId: runParams.agentId, + expectedSessionId: runParams.sessionId, + ...(runParams.expectedLifecycleRevision !== undefined + ? { expectedLifecycleRevision: runParams.expectedLifecycleRevision } + : {}), + ...(runParams.expectedWriterRunId !== undefined + ? { expectedWriterRunId: runParams.expectedWriterRunId } + : {}), + storePath: runParams.storePath, + idempotencyKey: `cli-assistant:${runParams.runId}`, + config: runParams.config, + beforeMessageWrite: runAgentHarnessBeforeMessageWriteHook, + message: buildAssistantMessage({ + model: { + api: "cli", + provider: runParams.provider, + id: params.modelId, + }, + content: [{ type: "text", text: params.text }], + stopReason: "stop", + usage: buildUsageWithNoCost({ + input: params.usage?.input, + output: params.usage?.output, + cacheRead: params.usage?.cacheRead, + cacheWrite: params.usage?.cacheWrite, + totalTokens: params.usage?.total, + }), + }), + }); + if (!result.ok) { + log.warn(`CLI assistant transcript persistence skipped: ${result.reason}`); + return { owned: result.code === "blocked" || result.code === "session-rebound" }; + } + return { owned: true, ...(result.anchor ? { terminalAnchor: result.anchor } : {}) }; + } catch (error) { + log.warn(`CLI assistant transcript persistence failed: ${formatErrorMessage(error)}`); + return { owned: false }; + } +} + +async function notifyCliUserMessagePersisted( + params: RunCliAgentParams, + message: Extract, + context: string, +): Promise { + try { + await Promise.resolve(params.onUserMessagePersisted?.(message)); + } catch (err) { + log.warn(`${context} notification failed: ${formatErrorMessage(err)}`); + } +} + +export async function persistCliRunBlock( + params: RunCliAgentParams, + block: { message: string; pluginId: string }, +): Promise { + const nowMs = Date.now(); + const redactedUserMessage = { + role: "user" as const, + content: [{ type: "text" as const, text: block.message }], + timestamp: nowMs, + idempotencyKey: `hook-block:before_agent_run:user:${params.runId}`, + __openclaw: { + beforeAgentRunBlocked: { + blockedBy: block.pluginId, + blockedAt: nowMs, + }, + }, + }; + try { + const persisted = await params.userTurnTranscriptRecorder?.persistBlocked(redactedUserMessage); + if (persisted) { + await notifyCliUserMessagePersisted( + params, + persisted.message, + "before_agent_run block user-turn persistence", + ); + return; + } + } catch (err) { + log.warn( + `before_agent_run block: failed to persist canonical CLI user message: ${formatErrorMessage( + err, + )}`, + ); + } + + try { + const sessionKey = params.sessionKey?.trim() || params.sessionId; + const agentId = params.agentId ?? resolveAgentIdFromSessionKey(sessionKey); + let sessionManager = params.sessionManager; + if (!sessionManager) { + const sessionTarget = params.sessionTarget ?? { + agentId, + sessionId: params.sessionId, + sessionKey, + storePath: + params.storePath ?? + resolveSessionStorePathCore(params.config?.session?.store, { + agentId, + }), + }; + const persistedEntry = await patchSessionEntryCore( + sessionTarget, + (entry, patchContext) => { + if (patchContext.existingEntry && entry.sessionId !== sessionTarget.sessionId) { + return null; + } + return { + sessionId: sessionTarget.sessionId, + updatedAt: Date.now(), + }; + }, + { + fallbackEntry: params.sessionEntry + ? undefined + : { sessionId: sessionTarget.sessionId, updatedAt: Date.now() }, + skipMaintenance: true, + }, + ); + if (persistedEntry?.sessionId !== sessionTarget.sessionId) { + // Skip only this stale blocked-message write; the outer runner still returns blocked. + return; + } + sessionManager = SessionManager.open(sessionTarget); + } + sessionManager.appendMessage( + redactedUserMessage as Parameters[0], + ); + sessionManager.flushPendingPersistence(); + } catch (err) { + log.warn( + `before_agent_run block: failed to persist redacted CLI user message: ${formatErrorMessage( + err, + )}`, + ); + } +} + +export async function finalizeCliContextEngineTurn(params: { + context: PreparedCliRunContext; + historyMessages: unknown[]; + assistantText: string; + terminalAnchor?: import("../../config/sessions/session-accessor.js").TranscriptEntryAnchor; + output: CliOutput; +}): Promise { + const { context } = params; + if (!context.contextEngine) { + return; + } + + const { params: runParams } = context; + const prePromptMessages = params.historyMessages.filter(isAgentMessage); + const turnMessages: AgentMessage[] = []; + if (context.contextEngineTurnPrompt) { + turnMessages.push(buildCliContextEngineUserMessage(context.contextEngineTurnPrompt)); + } + if (params.assistantText) { + turnMessages.push( + buildCliContextEngineAssistantMessage({ + text: params.assistantText, + provider: runParams.provider, + model: context.modelId, + usage: params.output.usage, + }), + ); + } + + const contextEngineHostSupport = buildGenericCliContextEngineHostSupport({ + backendId: context.backendResolved.id, + }); + const finalizeTurn = async (transcript: { + messagesSnapshot: AgentMessage[]; + prePromptMessageCount: number; + sessionManager?: SessionManager; + withSessionManagerRewriteLock: (operation: () => Promise | T) => Promise; + }) => { + let deferredTurnMaintenance: Promise | undefined; + const result = await finalizeHarnessContextEngineTurn({ + contextEngine: context.contextEngine, + promptError: false, + aborted: runParams.abortSignal?.aborted === true, + yieldAborted: false, + sessionIdUsed: runParams.sessionId, + sessionKey: runParams.sessionKey, + sessionFile: runParams.sessionFile, + isHeartbeat: isHeartbeatLifecycleRunKind(runParams.bootstrapContextRunKind), + messagesSnapshot: transcript.messagesSnapshot, + prePromptMessageCount: transcript.prePromptMessageCount, + sessionManager: transcript.sessionManager, + config: context.contextEngineConfig, + contextEngineHostSupport, + providerId: runParams.provider, + modelId: context.modelId, + runMaintenance: async (maintenanceParams) => + await runHarnessContextEngineMaintenance({ + ...maintenanceParams, + withSessionManagerRewriteLock: transcript.withSessionManagerRewriteLock, + onDeferredMaintenance: (promise) => { + deferredTurnMaintenance = promise; + }, + }), + warn: (message) => log.warn(message), + }); + if (result.postTurnFinalizationSucceeded && deferredTurnMaintenance) { + context.contextEngineDeferredTurnMaintenance = deferredTurnMaintenance; + } + }; + const admission = runParams.userTurnTranscriptRecorder?.getAdmissionReceipt(); + if (runParams.onContextEngineTurnCandidate) { + if (admission && params.terminalAnchor) { + runParams.onContextEngineTurnCandidate({ + boundary: { admission, terminal: params.terminalAnchor }, + sessionIdUsed: runParams.sessionId, + sessionKey: runParams.sessionKey, + sessionTarget: runParams.sessionTarget, + sessionFile: runParams.sessionFile, + promptError: false, + aborted: runParams.abortSignal?.aborted === true, + yieldAborted: false, + contextEngineHostSupport, + providerId: runParams.provider, + modelId: context.modelId, + config: context.contextEngineConfig, + isHeartbeat: isHeartbeatLifecycleRunKind(runParams.bootstrapContextRunKind), + }); + } + } else { + await finalizeTurn({ + messagesSnapshot: [...prePromptMessages, ...turnMessages], + prePromptMessageCount: prePromptMessages.length, + withSessionManagerRewriteLock: async (operation) => await operation(), + }); + } +} diff --git a/src/agents/code-mode.wait.test.ts b/src/agents/code-mode.wait.test.ts index 6bf24b3a0c02..474f32f06ef8 100644 --- a/src/agents/code-mode.wait.test.ts +++ b/src/agents/code-mode.wait.test.ts @@ -650,7 +650,10 @@ describe("Code Mode wait, scope, and suspended runs", () => { ); expect(first.status).toBe("waiting"); expect(first.output).toEqual([{ type: "text", text: "before timeout" }]); - expect(first.pendingToolCalls).toEqual([expect.objectContaining({ method: "callValue" })]); + // The fast call may settle as the snapshot is parked, but the slow call must remain pending. + expect(first.pendingToolCalls).toContainEqual( + expect.objectContaining({ id: "bridge:callValue:2", method: "callValue" }), + ); const runId = first.runId; expect(typeof runId).toBe("string"); if (typeof runId !== "string") { From e4da1c8d8b001755cbc8952a462f71581ce4c452 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:22:36 -0700 Subject: [PATCH 071/165] improve: speed up secrets runtime coverage tests (#122538) * test: speed up secrets runtime coverage * test: respect extension contract boundary --------- Co-authored-by: Amp --- src/secrets/runtime.coverage.test.ts | 76 +++++++++++++++++++--------- 1 file changed, 53 insertions(+), 23 deletions(-) diff --git a/src/secrets/runtime.coverage.test.ts b/src/secrets/runtime.coverage.test.ts index 40e7917453bc..da1f66bbde09 100644 --- a/src/secrets/runtime.coverage.test.ts +++ b/src/secrets/runtime.coverage.test.ts @@ -5,6 +5,7 @@ import path from "node:path"; import { afterAll, beforeAll, describe, expect, test, vi } from "vitest"; import type { AuthProfileStore } from "../agents/auth-profiles.js"; import type { OpenClawConfig } from "../config/config.js"; +import { loadBundledPluginPublicSurface } from "../plugin-sdk/test-helpers/public-surface-loader.js"; import type { PluginOrigin, PluginWebFetchProviderEntry, @@ -27,6 +28,7 @@ const COVERAGE_WEB_PROVIDER_PLUGIN_IDS = vi.hoisted(() => ({ ], fetch: ["firecrawl"], })); +const COVERAGE_CHANNEL_CONTRACTS = vi.hoisted(() => new Map()); vi.mock("../plugins/capability-provider-runtime.js", () => ({ resolvePluginCapabilityProviders: () => [], @@ -56,6 +58,11 @@ vi.mock("../plugins/plugin-metadata-snapshot.js", () => { }; }); +vi.mock("./channel-contract-api.js", () => ({ + loadChannelSecretContractApi: ({ channelId }: { channelId: string }) => + COVERAGE_CHANNEL_CONTRACTS.get(channelId), +})); + vi.mock("./runtime-web-tools-manifest.runtime.js", () => ({ resolveManifestContractPluginIds: ({ contract }: { contract: string }) => { if (contract === "webSearchProviders") { @@ -289,6 +296,15 @@ function loadCoverageRegistryEntries(): SecretRegistryEntry[] { } const COVERAGE_REGISTRY_ENTRIES = loadCoverageRegistryEntries(); +const COVERAGE_BUNDLED_CHANNEL_IDS = [ + ...new Set( + COVERAGE_REGISTRY_ENTRIES.flatMap((entry) => { + const [scope, channelId] = entry.id.split("."); + return scope === "channels" && channelId && channelId !== "qqbot" ? [channelId] : []; + }), + ), +]; + const DEBUG_COVERAGE_BATCHES = process.env.OPENCLAW_DEBUG_RUNTIME_COVERAGE === "1"; const RUNTIME_COVERAGE_TEST_TIMEOUT_MS = 240_000; const COVERAGE_CONFIG_PLUGIN_SOURCE_DIRS = new Map([ @@ -902,34 +918,48 @@ function toCoverageBatchCase(batch: SecretRegistryEntry[]) { describe("secrets runtime target coverage", () => { beforeAll(async () => { - const [sharedRuntime, resolver, configCollectors, authCollectors, runtimeWebTools] = - await Promise.all([ - import("./runtime-shared.js"), - import("./resolve.js"), - import("./runtime-config-collectors.js"), - import("./runtime-auth-collectors.js"), - import("./runtime-web-tools.js"), - ]); + const [ + sharedRuntime, + resolver, + configCollectors, + authCollectors, + runtimeWebTools, + channelContracts, + officialExternalChannelContract, + ] = await Promise.all([ + import("./runtime-shared.js"), + import("./resolve.js"), + import("./runtime-config-collectors.js"), + import("./runtime-auth-collectors.js"), + import("./runtime-web-tools.js"), + Promise.all( + COVERAGE_BUNDLED_CHANNEL_IDS.map( + async (channelId) => + [ + channelId, + await loadBundledPluginPublicSurface({ + pluginId: channelId, + artifactBasename: "secret-contract-api.js", + }), + ] as const, + ), + ), + import("./official-external-channel-secret-contract.js"), + ]); + for (const [channelId, contract] of channelContracts) { + COVERAGE_CHANNEL_CONTRACTS.set(channelId, contract); + } + const qqbotContract = + officialExternalChannelContract.loadOfficialExternalChannelSecretContractApi("qqbot"); + if (!qqbotContract) { + throw new Error("missing coverage contract for official QQBot channel"); + } + COVERAGE_CHANNEL_CONTRACTS.set("qqbot", qqbotContract); ({ applyResolvedAssignments, createResolverContext } = sharedRuntime); ({ resolveSecretRefValues } = resolver); ({ collectConfigAssignments } = configCollectors); ({ collectAuthStoreAssignments } = authCollectors); ({ resolveRuntimeWebTools } = runtimeWebTools); - - const googleChatBatch = OPENCLAW_CORE_COVERAGE_BATCHES.find((batch) => - batch.some((entry) => entry.id === "channels.googlechat.serviceAccount"), - ); - if (googleChatBatch) { - await expectOpenClawCoverageBatchResolved("openclaw.json core", googleChatBatch); - } - const webProviderBatch = OPENCLAW_PLUGIN_COVERAGE_BATCHES.find((batch) => - batch.some((entry) => entry.id.includes(".config.webSearch.")), - ); - if (webProviderBatch) { - // Warm the shared plugin snapshot once; individual target assertions then - // measure resolution work instead of one-time manifest discovery. - await expectOpenClawCoverageBatchResolved("openclaw.json plugins", webProviderBatch); - } }); describe("openclaw.json core and channel registry targets", () => { From 1672d78d17d48e80942319954d7e5d3411488ff6 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 12 Aug 2026 16:23:33 +0800 Subject: [PATCH 072/165] refactor(plugins): share bounded run id tracking (#122362) --- src/plugins/host-hook-runtime.ts | 31 +++++++++++++------------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/src/plugins/host-hook-runtime.ts b/src/plugins/host-hook-runtime.ts index ce8596a95a35..9f99dff56c76 100644 --- a/src/plugins/host-hook-runtime.ts +++ b/src/plugins/host-hook-runtime.ts @@ -40,7 +40,7 @@ type PluginHostRuntimeState = { }; const PLUGIN_HOST_RUNTIME_STATE_KEY = Symbol.for("openclaw.pluginHostRuntimeState"); -const CLOSED_RUN_IDS_MAX = 512; +const TRACKED_RUN_IDS_MAX = 512; const PLUGIN_TERMINAL_EVENT_CLEANUP_WAIT_MS = 5_000; const log = createSubsystemLogger("plugins/host-hooks"); @@ -63,34 +63,29 @@ function copyJsonValue(value: PluginJsonValue): PluginJsonValue { return structuredClone(value); } -function markPluginRunClosed(runId: string): void { - const state = getPluginHostRuntimeState(); - state.closedRunIds.delete(runId); - state.closedRunIds.add(runId); - while (state.closedRunIds.size > CLOSED_RUN_IDS_MAX) { - const oldest = state.closedRunIds.values().next().value; +function rememberBoundedRunId(runIds: Set, runId: string): void { + runIds.delete(runId); + runIds.add(runId); + + while (runIds.size > TRACKED_RUN_IDS_MAX) { + const oldest = runIds.values().next().value; if (oldest === undefined) { break; } - state.closedRunIds.delete(oldest); + runIds.delete(oldest); } } +function markPluginRunClosed(runId: string): void { + rememberBoundedRunId(getPluginHostRuntimeState().closedRunIds, runId); +} + function isPluginRunClosed(runId: string): boolean { return getPluginHostRuntimeState().closedRunIds.has(runId); } function markTerminalEventCleanupExpired(runId: string): void { - const state = getPluginHostRuntimeState(); - state.terminalEventCleanupExpiredRunIds.delete(runId); - state.terminalEventCleanupExpiredRunIds.add(runId); - while (state.terminalEventCleanupExpiredRunIds.size > CLOSED_RUN_IDS_MAX) { - const oldest = state.terminalEventCleanupExpiredRunIds.values().next().value; - if (oldest === undefined) { - break; - } - state.terminalEventCleanupExpiredRunIds.delete(oldest); - } + rememberBoundedRunId(getPluginHostRuntimeState().terminalEventCleanupExpiredRunIds, runId); } function isTerminalEventCleanupExpired(runId: string): boolean { From 432ccac74b8cf489675bc8b66c0152ad7e1bac41 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:36:54 -0700 Subject: [PATCH 073/165] fix(channels): honor terminal reaction holds (#122544) Serialize done and error holds before restoring initial reactions, and restore Slack error reactions through the shared lifecycle. --- .../dispatch.preview-fallback.test.ts | 10 +- .../src/monitor/message-handler/dispatch.ts | 1 + .../status-reactions.slack-lifecycle.test.ts | 13 ++- src/channels/status-reactions.test.ts | 97 ++++++++++++++++--- src/channels/status-reactions.ts | 54 +++++++++-- 5 files changed, 149 insertions(+), 26 deletions(-) diff --git a/extensions/slack/src/monitor/message-handler/dispatch.preview-fallback.test.ts b/extensions/slack/src/monitor/message-handler/dispatch.preview-fallback.test.ts index 01e316a864f8..115aff7a7355 100644 --- a/extensions/slack/src/monitor/message-handler/dispatch.preview-fallback.test.ts +++ b/extensions/slack/src/monitor/message-handler/dispatch.preview-fallback.test.ts @@ -1957,9 +1957,13 @@ describe("dispatchPreparedSlackMessage preview fallback", () => { }); expect(statusReactionControllerMock.setQueued).toHaveBeenCalledTimes(1); expect(statusReactionControllerMock.setDone).toHaveBeenCalledTimes(1); + expect(statusReactionControllerMock.restoreInitial).toHaveBeenCalledTimes(1); + expect(statusReactionControllerMock.setDone.mock.invocationCallOrder[0]).toBeLessThan( + statusReactionControllerMock.restoreInitial.mock.invocationCallOrder[0] ?? 0, + ); }); - it("marks a recovered agent failure as failed after delivering its visible error reply", async () => { + it("marks a recovered agent failure as failed then restores its initial reaction", async () => { mockedAgentRunTerminalOutcome = "failed"; mockedNativeStreaming = true; mockedSlackStreamingMode = "progress"; @@ -1985,6 +1989,10 @@ describe("dispatchPreparedSlackMessage preview fallback", () => { expect(collectNativeTaskUpdates().at(-1)).toEqual(expect.objectContaining({ status: "error" })); expect(statusReactionControllerMock.setError).toHaveBeenCalledTimes(1); expect(statusReactionControllerMock.setDone).not.toHaveBeenCalled(); + expect(statusReactionControllerMock.restoreInitial).toHaveBeenCalledTimes(1); + expect(statusReactionControllerMock.setError.mock.invocationCallOrder[0]).toBeLessThan( + statusReactionControllerMock.restoreInitial.mock.invocationCallOrder[0] ?? 0, + ); }); it("keeps Slack lifecycle reactions off by default when an ack reaction exists", async () => { diff --git a/extensions/slack/src/monitor/message-handler/dispatch.ts b/extensions/slack/src/monitor/message-handler/dispatch.ts index 90f1ff6b0890..513a98b1f6ca 100644 --- a/extensions/slack/src/monitor/message-handler/dispatch.ts +++ b/extensions/slack/src/monitor/message-handler/dispatch.ts @@ -572,6 +572,7 @@ export async function dispatchPreparedSlackMessage(prepared: PreparedSlackMessag if (statusReactionsEnabled) { if (dispatchError || agentRunFailed) { await statusReactions.setError(); + void statusReactions.restoreInitial(); } else if (anyReplyDelivered) { await statusReactions.setDone(); void statusReactions.restoreInitial(); diff --git a/src/channels/status-reactions.slack-lifecycle.test.ts b/src/channels/status-reactions.slack-lifecycle.test.ts index 4c2c5e8acf86..fd6879a75a70 100644 --- a/src/channels/status-reactions.slack-lifecycle.test.ts +++ b/src/channels/status-reactions.slack-lifecycle.test.ts @@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { createStatusReactionController, DEFAULT_EMOJIS, + DEFAULT_TIMING, type StatusReactionAdapter, } from "./status-reactions.js"; @@ -67,7 +68,9 @@ describe("Slack status reaction lifecycle", () => { expect(active.has(WEB_SEARCH_TOOL_EMOJI)).toBe(true); expect(active.has(DEFAULT_EMOJIS.thinking)).toBe(true); - await ctrl.setDone(); + const donePromise = ctrl.setDone(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.doneHoldMs); + await donePromise; expect(active.has(DEFAULT_EMOJIS.done)).toBe(true); expect(active.has(WEB_SEARCH_TOOL_EMOJI)).toBe(false); expect(active.has(DEFAULT_EMOJIS.thinking)).toBe(false); @@ -90,7 +93,9 @@ describe("Slack status reaction lifecycle", () => { await vi.advanceTimersByTimeAsync(10); expect(active.has("eyes")).toBe(true); - await ctrl.setError(); + const errorPromise = ctrl.setError(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.errorHoldMs); + await errorPromise; expect(active.has(DEFAULT_EMOJIS.error)).toBe(true); expect(active.has("eyes")).toBe(false); @@ -155,7 +160,9 @@ describe("Slack status reaction lifecycle", () => { void ctrl.setQueued(); await vi.advanceTimersByTimeAsync(10); - await ctrl.setDone(); + const donePromise = ctrl.setDone(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.doneHoldMs); + await donePromise; await ctrl.restoreInitial(); diff --git a/src/channels/status-reactions.test.ts b/src/channels/status-reactions.test.ts index 8609a2ae93be..9af43b26a640 100644 --- a/src/channels/status-reactions.test.ts +++ b/src/channels/status-reactions.test.ts @@ -252,23 +252,61 @@ describe("createStatusReactionController", () => { name: "setDone", run: (controller: ReturnType) => controller.setDone(), expected: DEFAULT_EMOJIS.done, + holdMs: DEFAULT_TIMING.doneHoldMs, }, { name: "setError", run: (controller: ReturnType) => controller.setError(), expected: DEFAULT_EMOJIS.error, + holdMs: DEFAULT_TIMING.errorHoldMs, }, ] as const; it.each(immediateTerminalCases)( - "should execute $name immediately without debounce", - async ({ run, expected }) => { + "should hold $name before an immediately queued restore", + async ({ run, expected, holdMs }) => { const { calls, controller } = createEnabledController(); - await run(controller); - await vi.runAllTimersAsync(); + void controller.setQueued(); + await vi.advanceTimersByTimeAsync(0); - expectSetEmojiCall(calls, expected); + let terminalResolved = false; + let restoreResolved = false; + const terminalPromise = run(controller).then(() => { + terminalResolved = true; + }); + const restorePromise = controller.restoreInitial().then(() => { + restoreResolved = true; + }); + await vi.advanceTimersByTimeAsync(0); + + expect(calls).toEqual([ + { method: "set", emoji: "👀" }, + { method: "set", emoji: expected }, + { method: "remove", emoji: "👀" }, + ]); + expect(terminalResolved).toBe(false); + expect(restoreResolved).toBe(false); + + await vi.advanceTimersByTimeAsync(holdMs - 1); + + expect(collectEmojisForMethod(calls, "set")).toEqual(["👀", expected]); + expect(terminalResolved).toBe(false); + expect(restoreResolved).toBe(false); + + await vi.advanceTimersByTimeAsync(1); + await Promise.all([terminalPromise, restorePromise]); + + expect(calls).toEqual([ + { method: "set", emoji: "👀" }, + { method: "set", emoji: expected }, + { method: "remove", emoji: "👀" }, + { method: "set", emoji: "👀" }, + { method: "remove", emoji: expected }, + ]); + expect(terminalResolved).toBe(true); + expect(restoreResolved).toBe(true); + expect(countCallsForEmoji(calls, expected)).toBe(2); }, ); @@ -277,6 +315,7 @@ describe("createStatusReactionController", () => { name: "ignore setThinking after setDone (terminal state)", terminal: (controller: ReturnType) => controller.setDone(), + holdMs: DEFAULT_TIMING.doneHoldMs, followup: (controller: ReturnType) => { void controller.setThinking(); }, @@ -285,16 +324,19 @@ describe("createStatusReactionController", () => { name: "ignore setTool after setError (terminal state)", terminal: (controller: ReturnType) => controller.setError(), + holdMs: DEFAULT_TIMING.errorHoldMs, followup: (controller: ReturnType) => { void controller.setTool("exec"); }, }, ] as const; - it.each(terminalIgnoreCases)("should $name", async ({ terminal, followup }) => { + it.each(terminalIgnoreCases)("should $name", async ({ terminal, holdMs, followup }) => { const { calls, controller } = createEnabledController(); - await terminal(controller); + const terminalPromise = terminal(controller); + await vi.advanceTimersByTimeAsync(holdMs); + await terminalPromise; const callsAfterTerminal = calls.length; followup(controller); await vi.advanceTimersByTimeAsync(1000); @@ -386,7 +428,9 @@ describe("createStatusReactionController", () => { void controller.setTool("exec"); await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.debounceMs); - await controller.setDone(); + const donePromise = controller.setDone(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.doneHoldMs); + await donePromise; const removeEmojis = collectEmojisForMethod(calls, "remove"); expect(removeEmojis).toEqual([ @@ -404,7 +448,9 @@ describe("createStatusReactionController", () => { void controller.setThinking(); await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.debounceMs); - await controller.setDone(); + const donePromise = controller.setDone(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.doneHoldMs); + await donePromise; expect(calls).toEqual([ { method: "set", emoji: DEFAULT_EMOJIS.thinking }, @@ -420,7 +466,9 @@ describe("createStatusReactionController", () => { void controller.setThinking(); await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.debounceMs); - await controller.setDone(); + const donePromise = controller.setDone(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.doneHoldMs); + await donePromise; await controller.restoreInitial(); expect(calls).toEqual([ @@ -511,11 +559,36 @@ describe("createStatusReactionController", () => { expectSetEmojiCall(calls, "🤔"); - await controller.setDone(); - await vi.runAllTimersAsync(); + const donePromise = controller.setDone(); + await vi.advanceTimersByTimeAsync(DEFAULT_TIMING.doneHoldMs); + await donePromise; expectSetEmojiCall(calls, "🎉"); }); + it("should cancel a terminal hold when explicitly cleared", async () => { + const { calls, controller } = createEnabledController(); + + void controller.setQueued(); + await vi.advanceTimersByTimeAsync(0); + let terminalResolved = false; + const terminalPromise = controller.setError().then(() => { + terminalResolved = true; + }); + await vi.advanceTimersByTimeAsync(0); + + expectSetEmojiCall(calls, DEFAULT_EMOJIS.error); + expect(terminalResolved).toBe(false); + expect(vi.getTimerCount()).toBe(1); + + const clearPromise = controller.clear(); + await vi.advanceTimersByTimeAsync(0); + await Promise.all([terminalPromise, clearPromise]); + + expect(terminalResolved).toBe(true); + expect(vi.getTimerCount()).toBe(0); + expect(collectEmojisForMethod(calls, "remove")).toEqual(["👀", DEFAULT_EMOJIS.error]); + }); + it("should use custom timing when provided", async () => { const { calls, controller } = createEnabledController({ timing: { diff --git a/src/channels/status-reactions.ts b/src/channels/status-reactions.ts index 3f33d5e89092..34690450f5f5 100644 --- a/src/channels/status-reactions.ts +++ b/src/channels/status-reactions.ts @@ -225,6 +225,8 @@ export function createStatusReactionController(params: { let debounceTimer: NodeJS.Timeout | null = null; let stallSoftTimer: NodeJS.Timeout | null = null; let stallHardTimer: NodeJS.Timeout | null = null; + let terminalHold: { timer: NodeJS.Timeout; resolve: () => void } | null = null; + let terminalHoldGeneration = 0; let finished = false; let chainPromise = Promise.resolve(); const activeEmojis = new Set(); @@ -234,7 +236,7 @@ export function createStatusReactionController(params: { return chainPromise; } - function clearAllTimers(): void { + function clearActivityTimers(): void { if (debounceTimer) { clearTimeout(debounceTimer); debounceTimer = null; @@ -249,6 +251,30 @@ export function createStatusReactionController(params: { } } + function cancelTerminalHold(): void { + terminalHoldGeneration += 1; + const hold = terminalHold; + if (!hold) { + return; + } + terminalHold = null; + clearTimeout(hold.timer); + hold.resolve(); + } + + function waitForTerminalHold(holdMs: number, generation: number): Promise { + if (holdMs <= 0 || generation !== terminalHoldGeneration) { + return Promise.resolve(); + } + return new Promise((resolve) => { + const timer = setTimeout(() => { + terminalHold = null; + resolve(); + }, holdMs); + terminalHold = { timer, resolve }; + }); + } + function clearDebounceTimer(): void { if (debounceTimer) { clearTimeout(debounceTimer); @@ -374,28 +400,30 @@ export function createStatusReactionController(params: { pendingEmoji = ""; } - function finishWithEmoji(emoji: string): Promise { + function finishWithEmoji(emoji: string, holdMs: number): Promise { if (!enabled) { return Promise.resolve(); } finished = true; - clearAllTimers(); + clearActivityTimers(); + const holdGeneration = terminalHoldGeneration; - // Return the updated chain so callers can wait for terminal cleanup. + // The serialized hold keeps an immediate restore queued, while explicit clear can cancel it. return enqueue(async () => { await applyEmoji(emoji); await removeActiveEmojis({ keepEmoji: emoji }); pendingEmoji = ""; + await waitForTerminalHold(holdMs, holdGeneration); }); } function setDone(): Promise { - return finishWithEmoji(emojis.done); + return finishWithEmoji(emojis.done, timing.doneHoldMs); } function setError(): Promise { - return finishWithEmoji(emojis.error); + return finishWithEmoji(emojis.error, timing.errorHoldMs); } async function clear(): Promise { @@ -403,7 +431,8 @@ export function createStatusReactionController(params: { return; } - clearAllTimers(); + clearActivityTimers(); + cancelTerminalHold(); finished = true; await enqueue(async () => { @@ -436,12 +465,17 @@ export function createStatusReactionController(params: { const pendingBeforeClear = pendingEmoji; const hadDebouncedPending = debounceTimer !== null; const hasExtraActiveEmoji = Array.from(activeEmojis).some((emoji) => emoji !== initialEmoji); - clearAllTimers(); - if (alreadyInitial && (!pendingBeforeClear || hadDebouncedPending) && !hasExtraActiveEmoji) { + clearActivityTimers(); + if ( + !finished && + alreadyInitial && + (!pendingBeforeClear || hadDebouncedPending) && + !hasExtraActiveEmoji + ) { pendingEmoji = ""; return; } - if (pendingBeforeClear === initialEmoji && !hadDebouncedPending) { + if (!finished && pendingBeforeClear === initialEmoji && !hadDebouncedPending) { await chainPromise; return; } From 92ed766673d558daac765b2bc985505463133918 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:38:18 -0700 Subject: [PATCH 074/165] fix(camera): publish URL downloads atomically (#122550) --- src/cli/nodes-camera.test.ts | 41 ++++++++++++++++++++++-- src/cli/nodes-camera.ts | 61 ++++++++++++++++++------------------ 2 files changed, 69 insertions(+), 33 deletions(-) diff --git a/src/cli/nodes-camera.test.ts b/src/cli/nodes-camera.test.ts index 494fa1202197..7a81243ca986 100644 --- a/src/cli/nodes-camera.test.ts +++ b/src/cli/nodes-camera.test.ts @@ -522,7 +522,7 @@ describe("nodes camera helpers", () => { expect(tracked.wasCanceled()).toBe(true); }); - it("removes partially written file when url stream fails", async () => { + it("preserves an existing file when url stream fails", async () => { const stream = new ReadableStream({ start(controller) { controller.enqueue(new TextEncoder().encode("partial")); @@ -533,6 +533,10 @@ describe("nodes camera helpers", () => { await withCameraTempDir(async (dir) => { const out = path.join(dir, "broken.bin"); + const sentinel = Buffer.from("existing-camera"); + await fs.writeFile(out, sentinel); + await fs.chmod(out, 0o640); + await expect( writeCameraPayloadToFile({ filePath: out, @@ -540,7 +544,40 @@ describe("nodes camera helpers", () => { expectedHost: "198.51.100.42", }), ).rejects.toThrow(/stream exploded/i); - await expectPathMissing(out); + await expect(fs.readFile(out)).resolves.toEqual(sentinel); + if (process.platform !== "win32") { + expect((await fs.stat(out)).mode & 0o777).toBe(0o640); + } + expect(await fs.readdir(dir)).toEqual(["broken.bin"]); + }); + }); + + it("rejects a url stream that closes without data", async () => { + const stream = new ReadableStream({ + start(controller) { + controller.close(); + }, + }); + stubFetchResponse(new Response(stream, { status: 200 })); + + await withCameraTempDir(async (dir) => { + const out = path.join(dir, "empty.bin"); + const sentinel = Buffer.from("existing-camera"); + await fs.writeFile(out, sentinel); + await fs.chmod(out, 0o640); + + await expect( + writeCameraPayloadToFile({ + filePath: out, + payload: { url: "https://198.51.100.42/empty.bin" }, + expectedHost: "198.51.100.42", + }), + ).rejects.toThrow(/empty download/i); + await expect(fs.readFile(out)).resolves.toEqual(sentinel); + if (process.platform !== "win32") { + expect((await fs.stat(out)).mode & 0o777).toBe(0o640); + } + expect(await fs.readdir(dir)).toEqual(["empty.bin"]); }); }); }); diff --git a/src/cli/nodes-camera.ts b/src/cli/nodes-camera.ts index af403f533448..ab9d0bde56d8 100644 --- a/src/cli/nodes-camera.ts +++ b/src/cli/nodes-camera.ts @@ -195,39 +195,38 @@ async function writeUrlToFile(filePath: string, url: string, opts: { expectedHos throw new Error(`failed to download ${url}: empty response body`); } - const fileHandle = await fs.open(filePath, "w"); - let thrown: unknown; - const reader = body.getReader(); - try { - while (true) { - const { done, value } = await reader.read(); - if (done) { - break; - } - if (!value || value.byteLength === 0) { - continue; - } - bytes += value.byteLength; - if (bytes > MAX_CAMERA_URL_DOWNLOAD_BYTES) { + await publishOutputFileAtomically({ + filePath, + writeTemp: async (tempPath) => { + const fileHandle = await fs.open(tempPath, "wx"); + const reader = body.getReader(); + try { + while (true) { + const { done, value } = await reader.read(); + if (done) { + break; + } + bytes += value.byteLength; + if (bytes > MAX_CAMERA_URL_DOWNLOAD_BYTES) { + await reader.cancel().catch(() => undefined); + throw new Error( + `writeUrlToFile: downloaded ${bytes} bytes, exceeds max ${MAX_CAMERA_URL_DOWNLOAD_BYTES}`, + ); + } + await fileHandle.write(value); + } + } catch (err) { await reader.cancel().catch(() => undefined); - throw new Error( - `writeUrlToFile: downloaded ${bytes} bytes, exceeds max ${MAX_CAMERA_URL_DOWNLOAD_BYTES}`, - ); + throw toErrorObject(err, "Non-Error thrown"); + } finally { + reader.releaseLock(); + await fileHandle.close(); } - await fileHandle.write(value); - } - } catch (err) { - thrown = err; - await reader.cancel().catch(() => undefined); - } finally { - reader.releaseLock(); - await fileHandle.close(); - } - - if (thrown) { - await fs.unlink(filePath).catch(() => {}); - throw toErrorObject(thrown, "Non-Error thrown"); - } + if (bytes === 0) { + throw new Error(`writeUrlToFile: empty download from ${url}`); + } + }, + }); } finally { await release(); } From 6d973d114f562b76861ce249a09df9ade174fb84 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 01:46:38 -0700 Subject: [PATCH 075/165] test: trim duplicate target registry coverage (#122555) Co-authored-by: Amp --- src/secrets/target-registry.test.ts | 102 ++-------------------------- 1 file changed, 6 insertions(+), 96 deletions(-) diff --git a/src/secrets/target-registry.test.ts b/src/secrets/target-registry.test.ts index 5e38506d238c..78627e9f1562 100644 --- a/src/secrets/target-registry.test.ts +++ b/src/secrets/target-registry.test.ts @@ -1,24 +1,22 @@ -/** Tests secret target registry matching and docs coverage. */ -import { beforeAll, describe, expect, it } from "vitest"; +/** Tests core secret target registry queries without plugin discovery. */ +import { describe, expect, it, vi } from "vitest"; import type { OpenClawConfig } from "../config/config.js"; import { buildTalkTestProviderConfig, TALK_TEST_PROVIDER_API_KEY_PATH, TALK_TEST_PROVIDER_ID, } from "../test-utils/talk-test-provider.js"; -import { getCoreSecretTargetRegistry } from "./target-registry-data.js"; import { - discoverConfigSecretTargets, discoverConfigSecretTargetsByIds, resolveConfigSecretTargetByPath, resolveSecretPlanTargetByPathCore, } from "./target-registry.js"; -describe("secret target registry", () => { - beforeAll(() => { - resolveConfigSecretTargetByPath(["channels", "googlechat", "serviceAccount"]); - }); +vi.mock("../plugins/plugin-metadata-snapshot.js", () => ({ + resolvePluginMetadataSnapshot: () => ({ plugins: [] }), +})); +describe("secret target registry", () => { it("supports filtered discovery by target ids", () => { const config = { ...buildTalkTestProviderConfig({ source: "env", provider: "default", id: "TALK_API_KEY" }), @@ -37,12 +35,6 @@ describe("secret target registry", () => { expect(targets[0]?.path).toBe(TALK_TEST_PROVIDER_API_KEY_PATH); }); - it("resolves config targets by exact path", () => { - const target = resolveConfigSecretTargetByPath(["channels", "googlechat", "serviceAccount"]); - - expect(target?.entry?.id).toBe("channels.googlechat.serviceAccount"); - }); - it("resolves talk realtime provider api key targets", () => { const target = resolveConfigSecretTargetByPath([ "talk", @@ -76,86 +68,4 @@ describe("secret target registry", () => { expect(configTarget?.providerId).toBe("openai"); expect(authProfileTarget?.entry.targetType).toBe("auth-profiles.api_key.key"); }); - - it("derives bundled web provider api key target paths from plugin manifests", () => { - const coreTargetIds = new Set(getCoreSecretTargetRegistry().map((entry) => entry.id)); - expect(coreTargetIds.has("plugins.entries.exa.config.webSearch.apiKey")).toBe(false); - expect(coreTargetIds.has("plugins.entries.firecrawl.config.webFetch.apiKey")).toBe(false); - - const target = resolveConfigSecretTargetByPath([ - "plugins", - "entries", - "exa", - "config", - "webSearch", - "apiKey", - ]); - - expect(target?.entry?.id).toBe("plugins.entries.exa.config.webSearch.apiKey"); - - const fetchTarget = resolveConfigSecretTargetByPath([ - "plugins", - "entries", - "firecrawl", - "config", - "webFetch", - "apiKey", - ]); - expect(fetchTarget?.entry?.id).toBe("plugins.entries.firecrawl.config.webFetch.apiKey"); - - const configuredTargets = discoverConfigSecretTargets({ - plugins: { - entries: { - exa: { - config: { - webSearch: { apiKey: "configured-plugin-key" }, - }, - }, - }, - }, - } as OpenClawConfig); - expect(configuredTargets.map((entry) => entry.entry.id)).toContain( - "plugins.entries.exa.config.webSearch.apiKey", - ); - }); - - it("derives bundled plugin SecretInput contract target paths from plugin manifests", () => { - const coreTargetIds = new Set(getCoreSecretTargetRegistry().map((entry) => entry.id)); - expect(coreTargetIds.has("plugins.entries.voice-call.config.twilio.authToken")).toBe(false); - expect(coreTargetIds.has("plugins.entries.codex.config.appServer.authToken")).toBe(false); - - const target = resolveConfigSecretTargetByPath([ - "plugins", - "entries", - "voice-call", - "config", - "tts", - "providers", - "elevenlabs", - "apiKey", - ]); - - expect(target?.entry?.id).toBe("plugins.entries.voice-call.config.tts.providers.*.apiKey"); - - const codexAuthTarget = resolveConfigSecretTargetByPath([ - "plugins", - "entries", - "codex", - "config", - "appServer", - "authToken", - ]); - expect(codexAuthTarget?.entry?.id).toBe("plugins.entries.codex.config.appServer.authToken"); - - const codexHeaderTarget = resolveConfigSecretTargetByPath([ - "plugins", - "entries", - "codex", - "config", - "appServer", - "headers", - "x-codex-client-session-token", - ]); - expect(codexHeaderTarget?.entry?.id).toBe("plugins.entries.codex.config.appServer.headers.*"); - }); }); From 3b01ea790560083ee1478e3af2e548d0acd232b2 Mon Sep 17 00:00:00 2001 From: Josh Avant <830519+joshavant@users.noreply.github.com> Date: Wed, 12 Aug 2026 03:50:37 -0500 Subject: [PATCH 076/165] fix(audit): show authenticated users for Gateway runs (#122484) * fix(audit): show authenticated users for Gateway runs * fix(audit): keep profile labels out of sessions * test(qa): verify session label retention at storage * fix(sessions): preserve canonical profile ownership * test(qa): require full identity inspection proof * docs(agents): preserve execution identity ownership boundary --- AGENTS.md | 1 + docs/cli/audit.md | 10 + docs/gateway/audit.md | 14 + src/agents/agent-command-admission-facts.ts | 20 + .../agent-command-execution-identity.test.ts | 139 ++++- .../agent-command-execution-identity.ts | 18 +- .../agent-turn/agent-run-execution-phase.ts | 6 + src/gateway/agent-turn/principal.ts | 5 +- src/gateway/local-user-ingress.ts | 124 +++++ .../session-creation-provenance.test.ts | 158 +++++- .../session-creation-provenance.ts | 5 +- src/gateway/server.sessions.create.test.ts | 41 +- .../server/ws-connection/connect-session.ts | 19 + ...essage-handler.post-connect-health.test.ts | 55 +- .../runtime/agent-run-identity-inspection.ts | 505 +++++++++++++++++- 15 files changed, 1080 insertions(+), 40 deletions(-) create mode 100644 src/agents/agent-command-admission-facts.ts create mode 100644 src/gateway/local-user-ingress.ts diff --git a/AGENTS.md b/AGENTS.md index ce6f603f0d95..f39b3bd65cb6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -170,6 +170,7 @@ Skills own workflows; root owns hard policy and routing. Product direction and m ## Execution Identity Audit - Execution identity is opt-in diagnostic provenance, never authorization or enforcement. Unknown facts stay unknown; record ingress or invoker facts only at their authoritative producer. Never infer identity from session keys, `runId`, or routing metadata. +- Frozen ingress identity facts are diagnostic audit input, not session-ownership state. Session provenance must use the current canonical authenticated profile ID and never retain a profile display label; only explicitly enabled execution-identity audit storage may retain its bounded, redacted form. - Invoker evidence is tri-state: tagged principal-bearing input is `present`, tagged principal-less input is `unknown`, and omission alone is `absent`. Validate the closed raw variant before projection or field dropping; reject malformed, mixed, untagged, or extra-field input instead of normalizing it to `unknown` or absence. - Each outer admitted turn owns one immutable `executionId` and `contextId`; `runId` is non-unique correlation. Retries, fallbacks, and recovery reuse the original admission identity. Only byte-identical canonical replay is idempotent. - Admission may only validate, bound, freeze, and enqueue through the shared audit writer. Admission validates only a recursively owned, enumerable, accessor-free data snapshot constructed from descriptors before schema checks or ordinary property reads; inherited properties are absent and accessors never run. No synchronous SQLite, schema, filesystem, HMAC-key, or readiness work. Audit failure never delays or aborts execution. diff --git a/docs/cli/audit.md b/docs/cli/audit.md index 85bde77e3dde..8f7075f6094a 100644 --- a/docs/cli/audit.md +++ b/docs/cli/audit.md @@ -124,6 +124,16 @@ ingress, an absent invoker, and `unattributed` coverage. Its admission receipt says `not-applicable` because no identity-aware policy or grant evaluation was proven. +For Gateway runs, a resolved authenticated profile can make the invoker +`present` and coverage `attribution-only`. Paired devices and shared credentials +do not establish a person: without a durable profile the invoker stays absent, +or `unknown` when authenticated user evidence promised a profile that could not +be resolved. Session creation retains the live canonical durable profile id so +profile linking does not orphan ownership, while run inspection consumes the +immutable connection-time audit fact. Ordinary session provenance stores no +display label. An optional bounded, secret-redacted label can be retained only +in execution identity after that audit storage is explicitly enabled. + JSON output is the Gateway result without lossy reformatting. An exact result contains one bounded V1 context (maximum 16 KiB), up to 100 decision receipts, coverage and missing-evidence codes, and an optional `nextDecisionCursor`. An ambiguous run diff --git a/docs/gateway/audit.md b/docs/gateway/audit.md index 4593687798d3..0d725cbac00e 100644 --- a/docs/gateway/audit.md +++ b/docs/gateway/audit.md @@ -91,6 +91,20 @@ this boundary. A run becomes `attribution-only` only when an authoritative ingress supplies an invoker fact. Neither state means that identity affected an allow or deny decision. +Authenticated Gateway attach records immutable audit facts once. Session +creation separately reads the live canonical durable profile id so a profile +link performed after attach cannot orphan session ownership. Ordinary session +provenance retains that id only; it does not retain a profile display label. +When execution identity recording is explicitly enabled, its audit context may +also retain the prepared display label after secret redaction and the +128-character bound. A resolved durable profile, including one established by +verified trusted-proxy or Tailscale identity, supplies a pseudonymized person +invoker. A paired device adds device assurance but never becomes a person. +Shared tokens, passwords, auth-none connections, and other profileless clients +remain unattributed. If authenticated user evidence promises a durable profile +but profile resolution fails, the invoker is `unknown` rather than guessed from +headers, device ids, connection ids, or credentials. + Each present context currently projects one run-admission receipt. Its outcome is `not-applicable`, its policy and grant references are empty, and its reason states that no identity-aware policy or grant evaluation was proven. This is diff --git a/src/agents/agent-command-admission-facts.ts b/src/agents/agent-command-admission-facts.ts new file mode 100644 index 000000000000..0da29dec541e --- /dev/null +++ b/src/agents/agent-command-admission-facts.ts @@ -0,0 +1,20 @@ +import type { ExecutionIdentityAdmissionFacts } from "../audit/execution-identity-admission.js"; + +type AgentCommandAdmissionFacts = Readonly< + Pick +>; + +const factsByIngress = new WeakMap(); + +export function attachAgentCommandAdmissionFacts( + ingress: object, + facts: AgentCommandAdmissionFacts, +): void { + factsByIngress.set(ingress, facts); +} + +export function getAgentCommandAdmissionFacts( + ingress: object, +): AgentCommandAdmissionFacts | undefined { + return factsByIngress.get(ingress); +} diff --git a/src/agents/agent-command-execution-identity.test.ts b/src/agents/agent-command-execution-identity.test.ts index 994018a3d198..8fe2e3ddbd59 100644 --- a/src/agents/agent-command-execution-identity.test.ts +++ b/src/agents/agent-command-execution-identity.test.ts @@ -1,7 +1,22 @@ -import { describe, expect, it } from "vitest"; -import { sanitizePublicAgentCommandIngressOpts } from "./agent-command-execution-identity.js"; +import { afterEach, describe, expect, it } from "vitest"; +import { + configureExecutionIdentityAdmissionSink, + type ExecutionIdentityAdmissionWork, +} from "../audit/execution-identity-admission.js"; +import { attachAgentCommandAdmissionFacts } from "./agent-command-admission-facts.js"; +import { + prepareAgentCommandExecutionIdentity, + sanitizePublicAgentCommandIngressOpts, +} from "./agent-command-execution-identity.js"; import type { AgentCommandIngressOpts } from "./command/types.js"; +let cleanupSink: (() => void) | undefined; + +afterEach(() => { + cleanupSink?.(); + cleanupSink = undefined; +}); + describe("sanitizePublicAgentCommandIngressOpts", () => { it("removes a forged cron creator authority capability from plain-JavaScript ingress", () => { const forgedCapability = { @@ -22,3 +37,123 @@ describe("sanitizePublicAgentCommandIngressOpts", () => { }); }); }); + +describe("Gateway agent command execution identity", () => { + it("carries only the prepared bounded, redacted label into opt-in run admission", async () => { + let work: ExecutionIdentityAdmissionWork | undefined; + const displayLabel = "Operator OPENAI_API_KEY=***".padEnd(128, "x"); + cleanupSink = configureExecutionIdentityAdmissionSink((candidate) => { + work = candidate; + return true; + }); + + const opts: AgentCommandIngressOpts = { + message: "attribute this run", + allowModelOverride: false, + }; + attachAgentCommandAdmissionFacts(opts, { + ingress: { + kind: "gateway-client", + boundary: "gateway.ws.authenticated-connect", + state: "present", + rawSourceRef: "profile-ada", + }, + invoker: { + state: "present", + kind: "person", + rawPrincipalRef: "profile-ada", + displayLabel, + }, + assurance: [ + { + kind: "durable-profile", + rawEvidenceRef: "profile-ada", + strength: "boundary-verified", + }, + ], + }); + const prepared = prepareAgentCommandExecutionIdentity({ + opts, + prepared: { + cfg: { logging: { audit: { enabled: true, executionIdentity: true } } }, + runId: "run-profiled", + sessionAgentId: "main", + sessionId: "session-profiled", + }, + ingress: { kind: "api", boundary: "agent-command.from-ingress", state: "unknown" }, + lifecycleGeneration: "generation-1", + }); + + await prepared.admit("embedded"); + + expect(work).toMatchObject({ + kind: "capture", + envelope: { + ingress: { + kind: "gateway-client", + boundary: "gateway.ws.authenticated-connect", + state: "present", + }, + invoker: { + state: "present", + kind: "person", + rawPrincipalRef: "profile-ada", + displayLabel: "Operator OPENAI_API_KEY=***", + }, + assurance: [ + { + kind: "durable-profile", + rawEvidenceRef: "profile-ada", + strength: "boundary-verified", + }, + ], + }, + }); + if (work?.kind !== "capture" || work.envelope.invoker?.state !== "present") { + throw new Error("expected captured present invoker"); + } + expect(work.envelope.invoker.displayLabel).toBe("Operator OPENAI_API_KEY=***"); + expect(work.envelope.invoker.displayLabel?.length).toBeLessThanOrEqual(128); + }); + + it("does not offer the prepared profile label to storage without execution audit opt-in", async () => { + let work: ExecutionIdentityAdmissionWork | undefined; + cleanupSink = configureExecutionIdentityAdmissionSink((candidate) => { + work = candidate; + return true; + }); + + const opts: AgentCommandIngressOpts = { + message: "do not retain this label", + allowModelOverride: false, + }; + attachAgentCommandAdmissionFacts(opts, { + ingress: { + kind: "gateway-client", + boundary: "gateway.ws.authenticated-connect", + state: "present", + }, + invoker: { + state: "present", + kind: "person", + rawPrincipalRef: "profile-ada", + displayLabel: "Ada", + }, + }); + const prepared = prepareAgentCommandExecutionIdentity({ + opts, + prepared: { + cfg: { logging: { audit: { enabled: true, executionIdentity: false } } }, + runId: "run-profiled-disabled", + sessionAgentId: "main", + sessionId: "session-profiled-disabled", + }, + ingress: { kind: "api", boundary: "agent-command.from-ingress", state: "unknown" }, + lifecycleGeneration: "generation-1", + }); + + await prepared.admit("embedded"); + + expect(work).toBeUndefined(); + }); +}); diff --git a/src/agents/agent-command-execution-identity.ts b/src/agents/agent-command-execution-identity.ts index 865c89b7997c..7816b418e342 100644 --- a/src/agents/agent-command-execution-identity.ts +++ b/src/agents/agent-command-execution-identity.ts @@ -8,6 +8,10 @@ import { prepareAgentRunAdmission, type OperationalRunInstanceRef, } from "./admitted-run-context.js"; +import { + attachAgentCommandAdmissionFacts, + getAgentCommandAdmissionFacts, +} from "./agent-command-admission-facts.js"; import type { AgentCommandGatewayIngressOpts, AgentCommandIngressOpts, @@ -38,13 +42,16 @@ function prepareAgentCommandRunAdmission(params: { runId: string; onAdmitted?: Parameters[0]["onAdmitted"]; }) { + const admissionFacts = getAgentCommandAdmissionFacts(params.operationalRunInstance) ?? { + ingress: params.ingress, + }; return prepareAgentRunAdmission({ cfg: params.cfg, operationalRunInstance: params.operationalRunInstance, facts: { runId: params.runId, agentId: params.agentId, - ingress: params.ingress, + ...admissionFacts, }, ...(params.admission ? { recovery: params.admission } : {}), ...(params.onAdmitted ? { onAdmitted: params.onAdmitted } : {}), @@ -96,13 +103,18 @@ export function prepareAgentCommandExecutionIdentity(params: { lifecycleGeneration: string; }) { const { opts, prepared } = params; + const operationalRunInstance = + opts.operationalRunInstance ?? createOperationalRunInstanceRef(prepared.runId); + const admissionFacts = getAgentCommandAdmissionFacts(params.opts.runContext ?? params.opts); + if (admissionFacts) { + attachAgentCommandAdmissionFacts(operationalRunInstance, admissionFacts); + } return executionIdentity.prepare({ admission: opts.executionIdentityAdmission, agentId: prepared.sessionAgentId, cfg: prepared.cfg, ingress: params.ingress, - operationalRunInstance: - opts.operationalRunInstance ?? createOperationalRunInstanceRef(prepared.runId), + operationalRunInstance, runId: prepared.runId, onAdmitted: async (admittedRunContext) => { await opts.onAdmittedRunContext?.(admittedRunContext); diff --git a/src/gateway/agent-turn/agent-run-execution-phase.ts b/src/gateway/agent-turn/agent-run-execution-phase.ts index 3a2fc9266abe..82c129a17cc7 100644 --- a/src/gateway/agent-turn/agent-run-execution-phase.ts +++ b/src/gateway/agent-turn/agent-run-execution-phase.ts @@ -1,6 +1,7 @@ import { randomUUID } from "node:crypto"; import { ErrorCodes, errorShape } from "../../../packages/gateway-protocol/src/index.js"; import { getAdmittedRunDelegatedAuthority } from "../../agents/admitted-run-context.js"; +import { attachAgentCommandAdmissionFacts } from "../../agents/agent-command-admission-facts.js"; import type { AgentRunTerminalOutcome } from "../../agents/agent-run-terminal-outcome.js"; import { claimExecApprovalFollowupRuntimeHandoff, @@ -41,6 +42,7 @@ import { buildRunUserTurnIdempotencyKey, createUserTurnTranscriptRecorder, } from "../../sessions/user-turn-transcript.js"; +import { getGatewayLocalUserIngress } from "../local-user-ingress.js"; import type { AgentRunRequest } from "../server-methods/agent-request-types.js"; import { createAgentRunModelSelectionHandler } from "../server-methods/agent-run-model-selection.js"; import { resolveSessionRuntimeCwd } from "../server-methods/agent-session-reset.js"; @@ -366,6 +368,10 @@ export function startAgentRunExecution(params: { restartRecoveryChannelContext?.sameChannelThreadRequired, ); + const localUserIngress = getGatewayLocalUserIngress(params.client); + if (localUserIngress) { + attachAgentCommandAdmissionFacts(runContext, localUserIngress.facts); + } dispatchAgentRunFromGateway({ cronCreatorAuthority: prepared.cronCreatorAuthority, ingressOpts: { diff --git a/src/gateway/agent-turn/principal.ts b/src/gateway/agent-turn/principal.ts index 33cf4f96468d..e4745467c3d4 100644 --- a/src/gateway/agent-turn/principal.ts +++ b/src/gateway/agent-turn/principal.ts @@ -2,6 +2,7 @@ import { GATEWAY_CLIENT_CAPS, hasGatewayClientCap, } from "../../../packages/gateway-protocol/src/client-info.js"; +import { transferGatewayLocalUserIngress } from "../local-user-ingress.js"; import type { GatewayClient, GatewayRequestContext } from "../server-methods/shared-types.js"; import type { AgentTurnPrincipal } from "./types.js"; @@ -10,7 +11,7 @@ export function captureAgentTurnPrincipal(client: GatewayClient | null): AgentTu if (!client) { return null; } - return { + const principal: AgentTurnPrincipal = { authenticatedUserId: client.authenticatedUserId, authenticatedUserProfile: client.authenticatedUserProfile, connId: client.connId, @@ -18,6 +19,8 @@ export function captureAgentTurnPrincipal(client: GatewayClient | null): AgentTu internal: client.internal, isDeviceTokenAuth: client.isDeviceTokenAuth, }; + transferGatewayLocalUserIngress(client, principal); + return principal; } /** Preserve capability-gated tool-event observation across agent turn entry paths. */ diff --git a/src/gateway/local-user-ingress.ts b/src/gateway/local-user-ingress.ts new file mode 100644 index 000000000000..ba3b282a5a14 --- /dev/null +++ b/src/gateway/local-user-ingress.ts @@ -0,0 +1,124 @@ +import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice"; +import type { ExecutionIdentityAdmissionFacts } from "../audit/execution-identity-admission.js"; +import { redactSensitiveText } from "../logging/redact.js"; +import type { GatewayAuthResult } from "./auth.js"; + +type GatewayLocalUserIngressFacts = Readonly< + Pick +>; + +type GatewayLocalUserIngress = Readonly<{ + facts: GatewayLocalUserIngressFacts; +}>; + +const ingressByOwner = new WeakMap(); + +function freezeLocalUserIngress(facts: GatewayLocalUserIngressFacts): GatewayLocalUserIngress { + Object.freeze(facts.ingress); + Object.freeze(facts.invoker); + for (const item of facts.assurance ?? []) { + Object.freeze(item); + } + Object.freeze(facts.assurance); + return Object.freeze({ facts: Object.freeze(facts) }); +} + +function safeDisplayLabel(value: string | null | undefined): string | undefined { + const label = value?.trim(); + return label + ? truncateUtf16Safe( + redactSensitiveText(redactSensitiveText(label, { mode: "tools" }), { mode: "tools" }), + 128, + ) + : undefined; +} + +/** Prepare attribution once from authenticated connection facts; credentials never become people. */ +export function prepareGatewayLocalUserIngress(params: { + authMethod?: GatewayAuthResult["method"]; + authenticatedUserExpected: boolean; + profile?: { profileId: string; displayName?: string | null }; + pairedDeviceId?: string; + isLocalClient: boolean; +}): GatewayLocalUserIngress { + const profileId = params.profile?.profileId.trim(); + const pairedDeviceId = params.pairedDeviceId?.trim(); + const displayLabel = safeDisplayLabel(params.profile?.displayName); + const assurance: NonNullable = []; + if (profileId) { + assurance.push({ + kind: "durable-profile", + rawEvidenceRef: profileId, + strength: "boundary-verified", + }); + } + if (params.authMethod === "trusted-proxy") { + assurance.push({ + kind: "trusted-proxy", + rawEvidenceRef: profileId ?? "gateway-auth:trusted-proxy", + strength: "boundary-verified", + }); + } else if (params.authMethod === "tailscale") { + assurance.push({ + kind: "tailscale-whois", + rawEvidenceRef: profileId ?? "gateway-auth:tailscale", + strength: "boundary-verified", + }); + } + if (pairedDeviceId) { + assurance.push({ + kind: "device-proof", + rawEvidenceRef: pairedDeviceId, + strength: "cryptographic", + }); + } + if (params.isLocalClient) { + assurance.push({ + kind: "local-process", + rawEvidenceRef: "gateway-transport:local", + strength: "boundary-verified", + }); + } + const rawSourceRef = profileId ?? pairedDeviceId; + return freezeLocalUserIngress({ + ingress: { + kind: "gateway-client", + boundary: "gateway.ws.authenticated-connect", + state: "present", + ...(rawSourceRef ? { rawSourceRef } : {}), + }, + ...(profileId + ? { + invoker: { + state: "present", + kind: "person", + rawPrincipalRef: profileId, + ...(displayLabel ? { displayLabel } : {}), + }, + } + : params.authenticatedUserExpected + ? { invoker: { state: "unknown" } } + : {}), + ...(assurance.length > 0 ? { assurance } : {}), + }); +} + +export function attachGatewayLocalUserIngress( + owner: object, + ingress: GatewayLocalUserIngress, +): void { + ingressByOwner.set(owner, ingress); +} + +export function getGatewayLocalUserIngress( + owner: object | null | undefined, +): GatewayLocalUserIngress | undefined { + return owner ? ingressByOwner.get(owner) : undefined; +} + +export function transferGatewayLocalUserIngress(source: object, target: object): void { + const ingress = ingressByOwner.get(source); + if (ingress) { + ingressByOwner.set(target, ingress); + } +} diff --git a/src/gateway/server-methods/session-creation-provenance.test.ts b/src/gateway/server-methods/session-creation-provenance.test.ts index cc8dbf777563..123fab7db8ab 100644 --- a/src/gateway/server-methods/session-creation-provenance.test.ts +++ b/src/gateway/server-methods/session-creation-provenance.test.ts @@ -1,16 +1,162 @@ import { describe, expect, it } from "vitest"; +import { + attachGatewayLocalUserIngress, + prepareGatewayLocalUserIngress, +} from "../local-user-ingress.js"; import { resolveAgentRunSessionCreation } from "./session-creation-provenance.js"; +function resolveWithIngress( + localUserIngress: ReturnType, + profileId?: string, +) { + const client = profileId ? { authenticatedUserProfile: { profileId } } : {}; + attachGatewayLocalUserIngress(client, localUserIngress); + return resolveAgentRunSessionCreation(client); +} + describe("agent run session creation provenance", () => { - it("uses a proven Gateway profile id", () => { - expect( - resolveAgentRunSessionCreation({ - authenticatedUserProfile: { profileId: "profile-ada" }, - }), - ).toEqual({ via: "run", actor: { type: "human", id: "profile-ada" } }); + it("uses a proven Gateway profile id without retaining its display label", () => { + const localUserIngress = prepareGatewayLocalUserIngress({ + authenticatedUserExpected: true, + profile: { profileId: "profile-ada", displayName: "Ada" }, + isLocalClient: false, + }); + + expect(resolveWithIngress(localUserIngress, "profile-ada")).toEqual({ + via: "run", + actor: { type: "human", id: "profile-ada" }, + }); + expect(localUserIngress.facts.invoker).toEqual({ + state: "present", + kind: "person", + rawPrincipalRef: "profile-ada", + displayLabel: "Ada", + }); + }); + + it("uses the live canonical profile id after a connection profile merge", () => { + const localUserIngress = prepareGatewayLocalUserIngress({ + authenticatedUserExpected: true, + profile: { profileId: "profile-before-merge", displayName: "Ada" }, + isLocalClient: false, + }); + + expect(resolveWithIngress(localUserIngress, "profile-after-merge")).toEqual({ + via: "run", + actor: { type: "human", id: "profile-after-merge" }, + }); + expect(localUserIngress.facts.invoker).toMatchObject({ + state: "present", + rawPrincipalRef: "profile-before-merge", + }); }); it("does not infer an actor for a profile-less wire client", () => { expect(resolveAgentRunSessionCreation({})).toEqual({ via: "run" }); }); + + it.each([ + { + name: "paired device", + input: { + authMethod: "device-token" as const, + authenticatedUserExpected: false, + pairedDeviceId: "device-browser", + isLocalClient: false, + }, + expected: { + ingress: expect.objectContaining({ rawSourceRef: "device-browser" }), + assurance: [ + { + kind: "device-proof", + rawEvidenceRef: "device-browser", + strength: "cryptographic", + }, + ], + }, + }, + { + name: "shared secret", + input: { + authMethod: "token" as const, + authenticatedUserExpected: false, + isLocalClient: false, + }, + expected: { ingress: expect.not.objectContaining({ rawSourceRef: expect.anything() }) }, + }, + ])("keeps a $name profile-less and unattributed", ({ input, expected }) => { + const localUserIngress = prepareGatewayLocalUserIngress(input); + + expect(localUserIngress.facts).toEqual(expect.objectContaining(expected)); + expect(localUserIngress.facts.invoker).toBeUndefined(); + expect(resolveWithIngress(localUserIngress)).toEqual({ via: "run" }); + }); + + it("keeps a trusted-proxy identity unknown when durable profile resolution is missing", () => { + const localUserIngress = prepareGatewayLocalUserIngress({ + authMethod: "trusted-proxy", + authenticatedUserExpected: true, + isLocalClient: false, + }); + + expect(localUserIngress.facts).toMatchObject({ + ingress: { kind: "gateway-client", state: "present" }, + invoker: { state: "unknown" }, + assurance: [ + { + kind: "trusted-proxy", + rawEvidenceRef: "gateway-auth:trusted-proxy", + strength: "boundary-verified", + }, + ], + }); + expect(resolveWithIngress(localUserIngress)).toEqual({ via: "run" }); + }); + + it("records both durable-profile and trusted-proxy assurance for a profiled proxy user", () => { + const localUserIngress = prepareGatewayLocalUserIngress({ + authMethod: "trusted-proxy", + authenticatedUserExpected: true, + profile: { profileId: "profile-proxy", displayName: "Proxy User" }, + isLocalClient: false, + }); + + expect(localUserIngress.facts.assurance).toEqual([ + { + kind: "durable-profile", + rawEvidenceRef: "profile-proxy", + strength: "boundary-verified", + }, + { + kind: "trusted-proxy", + rawEvidenceRef: "profile-proxy", + strength: "boundary-verified", + }, + ]); + }); + + it("keeps a bounded, redacted profile label transient for opt-in run auditing", () => { + const secret = "sk-1234567890abcdef"; + const localUserIngress = prepareGatewayLocalUserIngress({ + authenticatedUserExpected: true, + profile: { + profileId: "profile-redacted", + displayName: `Operator OPENAI_API_KEY=${secret} ${"x".repeat(256)}`, + }, + isLocalClient: false, + }); + + const invoker = localUserIngress.facts.invoker; + expect(invoker).toMatchObject({ state: "present" }); + if (invoker?.state !== "present") { + throw new Error("expected present invoker"); + } + expect(invoker.displayLabel).toContain("OPENAI_API_KEY=***"); + expect(invoker.displayLabel).not.toContain(secret); + expect(invoker.displayLabel?.length).toBeLessThanOrEqual(128); + expect(resolveWithIngress(localUserIngress, "profile-redacted")).toEqual({ + via: "run", + actor: { type: "human", id: "profile-redacted" }, + }); + }); }); diff --git a/src/gateway/server-methods/session-creation-provenance.ts b/src/gateway/server-methods/session-creation-provenance.ts index 05a4477cc160..8408c750de9e 100644 --- a/src/gateway/server-methods/session-creation-provenance.ts +++ b/src/gateway/server-methods/session-creation-provenance.ts @@ -52,9 +52,8 @@ export function resolveOperatorSessionCreation( }; } const profileId = client?.authenticatedUserProfile?.profileId; - // Actor only when proven: a profile-less wire connection may be an agent-tool - // client on a remote topology, so claiming a human actor would misattribute - // agent-caused creations. Absent actor means unknown, never inferred. + // Profile linking can canonicalize this id after connection attach, so session + // ownership follows the live trusted profile while audit keeps its frozen facts. return { via: "operator", ...(profileId ? { actor: { type: "human" as const, id: profileId } } : {}), diff --git a/src/gateway/server.sessions.create.test.ts b/src/gateway/server.sessions.create.test.ts index 399ed2d1d44c..a8761d05b228 100644 --- a/src/gateway/server.sessions.create.test.ts +++ b/src/gateway/server.sessions.create.test.ts @@ -38,6 +38,10 @@ import { import { closeOpenClawStateDatabaseForTest } from "../state/openclaw-state-db.js"; import { createOpenClawTestState } from "../test-utils/openclaw-test-state.js"; import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js"; +import { + attachGatewayLocalUserIngress, + prepareGatewayLocalUserIngress, +} from "./local-user-ingress.js"; import { resolveGatewaySessionStoreTarget } from "./session-utils.js"; import { agentCommandMock, @@ -3088,8 +3092,25 @@ test("sessions.create preserves write-scoped fresh keyed model selection but gat }); test("sessions.create stamps trusted operator provenance and records created", async () => { - await createSessionStoreDir(); + const { storePath } = await createSessionStoreDir(); const profileId = "profile-session-creator"; + const client = { + connect: { scopes: ["operator.write"] }, + authenticatedUserProfile: { + profileId, + displayName: "Test Operator", + hasAvatar: false, + updatedAt: 1, + }, + }; + attachGatewayLocalUserIngress( + client, + prepareGatewayLocalUserIngress({ + authenticatedUserExpected: true, + profile: { profileId, displayName: "Test Operator" }, + isLocalClient: false, + }), + ); const created = await directSessionReq<{ key?: string; entry?: { @@ -3097,21 +3118,7 @@ test("sessions.create stamps trusted operator provenance and records created", a createdActor?: { type: string; id?: string }; createdAt?: number; }; - }>( - "sessions.create", - { agentId: "main" }, - { - client: { - connect: { scopes: ["operator.write"] }, - authenticatedUserProfile: { - profileId, - displayName: "Test Operator", - hasAvatar: false, - updatedAt: 1, - }, - } as never, - }, - ); + }>("sessions.create", { agentId: "main" }, { client: client as never }); expect(created.ok).toBe(true); expect(created.payload?.entry).toMatchObject({ @@ -3119,7 +3126,9 @@ test("sessions.create stamps trusted operator provenance and records created", a createdActor: { type: "human", id: profileId }, createdAt: expect.any(Number), }); + expect(created.payload?.entry).not.toHaveProperty("createdActor.label"); const key = requireNonEmptyString(created.payload?.key, "created session key"); + expect(loadSessionEntry({ sessionKey: key, storePath })).not.toHaveProperty("createdActor.label"); expect(listSessionStateEventsSince(key, "main", 0, 20).events).toContainEqual( expect.objectContaining({ kind: "created", diff --git a/src/gateway/server/ws-connection/connect-session.ts b/src/gateway/server/ws-connection/connect-session.ts index eaef0409ff7b..9c8ff9bb0ba0 100644 --- a/src/gateway/server/ws-connection/connect-session.ts +++ b/src/gateway/server/ws-connection/connect-session.ts @@ -33,6 +33,10 @@ import { import { resolveRuntimeServiceVersion } from "../../../version.js"; import { verifyAgentRuntimeIdentityToken } from "../../agent-runtime-identity-token.js"; import { buildAuthenticatedPresenceUser } from "../../authenticated-presence-user.js"; +import { + attachGatewayLocalUserIngress, + prepareGatewayLocalUserIngress, +} from "../../local-user-ingress.js"; import { APPROVALS_SCOPE } from "../../method-scopes.js"; import { serializeEventPayload } from "../../node-registry.js"; import { isOperatorApprovalRuntimeToken } from "../../operator-approval-runtime-token.js"; @@ -317,6 +321,20 @@ export async function attachAuthenticatedGatewayConnect( : {}), } : undefined; + const localUserIngress = prepareGatewayLocalUserIngress({ + authMethod, + authenticatedUserExpected: Boolean(authenticatedUserId), + ...(authenticatedUserProfile + ? { + profile: { + profileId: authenticatedUserProfile.profileId, + displayName: authenticatedUserProfile.displayName, + }, + } + : {}), + ...(device?.id ? { pairedDeviceId: device.id } : {}), + isLocalClient, + }); if (usesLegacyNodeProtocol) { logWsControl.warn( `legacy node protocol accepted conn=${connId} client=${formatForLog(clientLabel)} v${formatForLog(connectParams.client.version)} min=${minProtocol} max=${maxProtocol} current=${PROTOCOL_VERSION}; upgrade recommended`, @@ -352,6 +370,7 @@ export async function attachAuthenticatedGatewayConnect( ? { pluginNodeCapabilitySurfaces } : {}), }; + attachGatewayLocalUserIngress(nextClient, localUserIngress); for (const entry of pendingPluginNodeCapabilities) { setClientPluginNodeCapability({ client: nextClient, diff --git a/src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts b/src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts index 7df04175c5f9..7a96dea62eb9 100644 --- a/src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts +++ b/src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts @@ -20,6 +20,7 @@ import { mintAgentRuntimeIdentityToken } from "../../agent-runtime-identity-toke import type { AuthRateLimiter } from "../../auth-rate-limit.js"; import type { ResolvedGatewayAuth } from "../../auth.js"; import type { HealthSummary } from "../../health/types.js"; +import { getGatewayLocalUserIngress } from "../../local-user-ingress.js"; import { getOperatorApprovalRuntimeToken } from "../../operator-approval-runtime-token.js"; import { handleGatewayRequest } from "../../server-methods.js"; import { resolveGatewayCronCreatorAuthorityAdmission } from "../../server-methods/cron-creator-authority-admission.js"; @@ -89,6 +90,12 @@ vi.mock("../../../config/config.js", () => ({ loadConfig: loadConfigMock, })); +function localUserIngressFor(client: unknown) { + return typeof client === "object" && client !== null + ? getGatewayLocalUserIngress(client) + : undefined; +} + vi.mock("../../../config/io.js", () => ({ getRuntimeConfig: loadConfigMock, })); @@ -726,6 +733,25 @@ describe("attachGatewayWsMessageHandler post-connect health refresh", () => { hasAvatar: false, }, }); + expect(localUserIngressFor(first.harness.client)).toMatchObject({ + facts: { + ingress: { + kind: "gateway-client", + rawSourceRef: profileId, + state: "present", + }, + invoker: { + state: "present", + kind: "person", + rawPrincipalRef: profileId, + displayLabel: "alice", + }, + assurance: expect.arrayContaining([ + expect.objectContaining({ kind: "durable-profile" }), + expect.objectContaining({ kind: "trusted-proxy" }), + ]), + }, + }); expect(setAvatar(profileId!, new Uint8Array([1, 2, 3]), "image/png").ok).toBe(true); const second = await connect("second"); @@ -817,6 +843,15 @@ describe("attachGatewayWsMessageHandler post-connect health refresh", () => { authenticatedUserIsTailscaleProvider: true, authenticatedUserProfile: { displayName: "Ada Lovelace", hasAvatar: false }, }); + expect(localUserIngressFor(harness.client)).toMatchObject({ + facts: { + invoker: { state: "present", kind: "person", displayLabel: "Ada Lovelace" }, + assurance: expect.arrayContaining([ + expect.objectContaining({ kind: "durable-profile" }), + expect.objectContaining({ kind: "tailscale-whois" }), + ]), + }, + }); expect(adoptTailscaleProfileAvatarMock).toHaveBeenCalledOnce(); }); expect(harness.socketSend).toHaveBeenCalled(); @@ -843,7 +878,7 @@ describe("attachGatewayWsMessageHandler post-connect health refresh", () => { }); }); - it("falls back to email identity when durable profile resolution fails", async () => { + it("keeps presence fallback but records unknown invoker when profile resolution fails", async () => { ensureProfileForEmailMock.mockImplementationOnce(() => { throw new Error("profile store unavailable"); }); @@ -858,6 +893,19 @@ describe("attachGatewayWsMessageHandler post-connect health refresh", () => { ); }); expect(harness.client).toMatchObject({ authenticatedUserId: "alice@example.com" }); + expect(localUserIngressFor(harness.client)).toMatchObject({ + facts: { + ingress: expect.not.objectContaining({ rawSourceRef: expect.anything() }), + invoker: { state: "unknown" }, + assurance: [ + { + kind: "trusted-proxy", + rawEvidenceRef: "gateway-auth:trusted-proxy", + strength: "boundary-verified", + }, + ], + }, + }); expect(harness.client).not.toMatchObject({ authenticatedUserProfile: expect.anything() }); expect(harness.logWsControl.warn).toHaveBeenCalledTimes(1); expect(harness.logWsControl.warn).toHaveBeenCalledWith( @@ -903,6 +951,11 @@ describe("attachGatewayWsMessageHandler post-connect health refresh", () => { }); expect(upsertPresenceMock).not.toHaveBeenCalled(); expect(harness.client).not.toMatchObject({ authenticatedUserId: expect.anything() }); + const localUserIngress = localUserIngressFor(harness.client); + expect(localUserIngress).toMatchObject({ + facts: { ingress: expect.not.objectContaining({ rawSourceRef: expect.anything() }) }, + }); + expect(localUserIngress?.facts.invoker).toBeUndefined(); expect(ensureProfileForEmailMock).not.toHaveBeenCalled(); }); diff --git a/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts b/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts index 4870cfbef578..2c8fa353c102 100644 --- a/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts +++ b/test/e2e/qa-lab/runtime/agent-run-identity-inspection.ts @@ -2,16 +2,35 @@ import { spawn } from "node:child_process"; import { createHash, randomUUID } from "node:crypto"; import fs from "node:fs/promises"; +import os from "node:os"; import path from "node:path"; import { DatabaseSync } from "node:sqlite"; +import { setTimeout as sleep } from "node:timers/promises"; import { pathToFileURL } from "node:url"; +import { isRecord } from "@openclaw/normalization-core/record-coerce"; +import { WebSocket, type ClientOptions, type RawData } from "ws"; import { QA_EVIDENCE_FILENAME, type QaEvidenceSummaryJson, } from "../../../../extensions/qa-lab/src/evidence-summary.js"; import { startQaGatewayChild } from "../../../../extensions/qa-lab/src/gateway-child.js"; import { startQaMockOpenAiServer } from "../../../../extensions/qa-lab/src/providers/mock-openai/server.js"; +import { buildDeviceAuthPayloadV3 } from "../../../../packages/gateway-client/src/device-auth.js"; +import { + GATEWAY_CLIENT_IDS, + GATEWAY_CLIENT_MODES, +} from "../../../../packages/gateway-protocol/src/client-info.js"; import type { AuditRunInspectResult } from "../../../../packages/gateway-protocol/src/index.js"; +import { + MIN_CLIENT_PROTOCOL_VERSION, + PROTOCOL_VERSION, +} from "../../../../packages/gateway-protocol/src/index.js"; +import { + loadOrCreateDeviceIdentity, + publicKeyRawBase64UrlFromPem, + signDevicePayload, + type DeviceIdentity, +} from "../../../../src/infra/device-identity.js"; import { formatErrorMessage } from "../../../../src/infra/errors.js"; import { createQaScriptEvidenceWriter, type QaScriptEvidenceStatus } from "./script-evidence.js"; @@ -37,6 +56,13 @@ const IDENTITY_FIELDS = [ "Applicable grants", "Assurance", ] as const; +const FRAME_TIMEOUT_MS = 20_000; +const GATEWAY_SCOPES = [ + "operator.admin", + "operator.pairing", + "operator.read", + "operator.write", +] as const; type ProducerOptions = { artifactBase: string; @@ -50,6 +76,211 @@ type ProofResult = { status: QaScriptEvidenceStatus; }; +type RawGatewayClient = { + frames: unknown[]; + socket: WebSocket; +}; + +function rawDataText(data: RawData): string { + if (Array.isArray(data)) { + return Buffer.concat(data.map((chunk) => Buffer.from(chunk))).toString("utf8"); + } + return Buffer.isBuffer(data) ? data.toString("utf8") : Buffer.from(data).toString("utf8"); +} + +async function openRawGatewayClient( + url: string, + headers?: Record, +): Promise { + const socket = new WebSocket(url, headers ? ({ headers } satisfies ClientOptions) : undefined); + const frames: unknown[] = []; + socket.on("message", (data) => frames.push(parseJson(rawDataText(data), "Gateway frame"))); + await new Promise((resolve, reject) => { + socket.once("open", resolve); + socket.once("error", reject); + }); + return { frames, socket }; +} + +async function waitForFrame( + client: RawGatewayClient, + predicate: (frame: unknown) => boolean, + startIndex = 0, +): Promise> { + const deadline = Date.now() + FRAME_TIMEOUT_MS; + while (Date.now() < deadline) { + const frame = client.frames.slice(startIndex).find(predicate); + if (isRecord(frame)) { + return frame; + } + await sleep(20); + } + throw new Error(`timed out waiting for Gateway frame: ${JSON.stringify(client.frames)}`); +} + +function responseFor(id: string) { + return (frame: unknown) => isRecord(frame) && frame.type === "res" && frame.id === id; +} + +async function closeRawGatewayClient(client: RawGatewayClient): Promise { + if (client.socket.readyState === WebSocket.CLOSED) { + return; + } + await new Promise((resolve) => { + client.socket.once("close", () => resolve()); + client.socket.close(); + setTimeout(resolve, 1_000).unref(); + }); +} + +async function connectRawDevice(params: { + device: DeviceIdentity; + headers?: Record; + token?: string; + wsUrl: string; +}): Promise<{ client: RawGatewayClient; connected: boolean }> { + const client = await openRawGatewayClient(params.wsUrl, params.headers); + const challenge = await waitForFrame( + client, + (frame) => isRecord(frame) && frame.type === "event" && frame.event === "connect.challenge", + ); + const challengePayload = challenge.payload; + if (!isRecord(challengePayload) || typeof challengePayload.nonce !== "string") { + throw new Error("Gateway connect challenge omitted its nonce"); + } + const clientInfo = { + id: GATEWAY_CLIENT_IDS.GATEWAY_CLIENT, + mode: GATEWAY_CLIENT_MODES.BACKEND, + platform: "linux", + version: "qa-local-user-ingress", + } as const; + const signedAt = Date.now(); + const devicePayload = buildDeviceAuthPayloadV3({ + deviceId: params.device.deviceId, + clientId: clientInfo.id, + clientMode: clientInfo.mode, + role: "operator", + scopes: [...GATEWAY_SCOPES], + signedAtMs: signedAt, + token: params.token, + nonce: challengePayload.nonce, + platform: clientInfo.platform, + }); + const requestId = `connect-${randomUUID()}`; + const startIndex = client.frames.length; + client.socket.send( + JSON.stringify({ + type: "req", + id: requestId, + method: "connect", + params: { + minProtocol: MIN_CLIENT_PROTOCOL_VERSION, + maxProtocol: PROTOCOL_VERSION, + client: clientInfo, + role: "operator", + scopes: [...GATEWAY_SCOPES], + caps: [], + ...(params.token ? { auth: { token: params.token } } : {}), + device: { + id: params.device.deviceId, + publicKey: publicKeyRawBase64UrlFromPem(params.device.publicKeyPem), + signature: signDevicePayload(params.device.privateKeyPem, devicePayload), + signedAt, + nonce: challengePayload.nonce, + }, + }, + }), + ); + const response = await waitForFrame(client, responseFor(requestId), startIndex); + return { client, connected: response.ok === true }; +} + +async function rawGatewayRequest( + client: RawGatewayClient, + method: string, + params: unknown, +): Promise { + const requestId = `request-${randomUUID()}`; + const startIndex = client.frames.length; + client.socket.send(JSON.stringify({ type: "req", id: requestId, method, params })); + const response = await waitForFrame(client, responseFor(requestId), startIndex); + if (response.ok !== true) { + throw new Error(`${method} failed: ${JSON.stringify(response.error)}`); + } + return response.payload as T; +} + +async function approveDeviceIfNeeded( + gateway: Awaited>, + deviceId: string, +): Promise { + const deadline = Date.now() + FRAME_TIMEOUT_MS; + while (Date.now() < deadline) { + const pairings = (await gateway.call("device.pair.list", {})) as { + pending?: Array<{ deviceId?: string; requestId?: string }>; + }; + const pending = pairings.pending?.find((candidate) => candidate.deviceId === deviceId); + if (pending?.requestId) { + await gateway.call("device.pair.approve", { requestId: pending.requestId }); + return; + } + await sleep(50); + } + throw new Error(`device pairing request was not visible for ${deviceId}`); +} + +async function createFakeTailscaleBinary(): Promise<{ + binaryDir: string; + cleanup: () => Promise; +}> { + const binaryDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-i1-tailscale-")); + try { + const binaryPath = path.join(binaryDir, "tailscale"); + await fs.writeFile( + binaryPath, + `#!/bin/sh +if [ "$1" = "--version" ]; then + echo "qa-tailscale 1.0" + exit 0 +fi +echo '{"UserProfile":{"LoginName":"operator@example.com","DisplayName":"Operator"}}' +`, + { encoding: "utf8", mode: 0o755 }, + ); + return { + binaryDir, + cleanup: async () => await fs.rm(binaryDir, { force: true, recursive: true }), + }; + } catch (error) { + await fs.rm(binaryDir, { force: true, recursive: true }); + throw error; + } +} + +async function runGatewayTurn( + client: RawGatewayClient, + message: string, + sessionKey: string, +): Promise { + const started = await rawGatewayRequest<{ runId?: unknown; status?: unknown }>(client, "agent", { + sessionKey, + message, + deliver: false, + idempotencyKey: randomUUID(), + }); + if (started.status !== "accepted" || typeof started.runId !== "string") { + throw new Error(`profiled Gateway run did not start: ${JSON.stringify(started)}`); + } + const terminal = await rawGatewayRequest<{ status?: unknown }>(client, "agent.wait", { + runId: started.runId, + timeoutMs: 60_000, + }); + if (terminal.status !== "ok") { + throw new Error(`profiled Gateway run did not finish: ${JSON.stringify(terminal)}`); + } + return started.runId; +} + async function updateExecutionIdentityConfig( configPath: string, values: { enabled?: boolean; executionIdentity: boolean }, @@ -143,6 +374,41 @@ function assertJsonProjection(result: AuditRunInspectResult, runId: string) { } } +function assertGatewayIdentityProjection( + result: AuditRunInspectResult, + expected: { coverage: "attribution-only" | "unattributed"; invoker: "absent" | "present" }, +) { + const context = requireIdentityContext(result); + if ( + context.ingress.kind !== "gateway-client" || + context.ingress.state !== "present" || + context.ingress.boundary !== "gateway.ws.authenticated-connect" + ) { + throw new Error("Gateway run did not retain its authenticated connection ingress"); + } + if ( + context.invoker.state !== expected.invoker || + context.coverageState !== expected.coverage || + context.representedSubject !== undefined + ) { + throw new Error( + `Gateway identity projection fabricated or lost a subject: ${JSON.stringify(context)}`, + ); + } + if (expected.invoker === "present") { + if ( + context.invoker.principal?.kind !== "person" || + context.invoker.principal.displayLabel !== "Operator" || + !context.assurance.some((item) => item.kind === "durable-profile") || + !context.assurance.some((item) => item.kind === "tailscale-whois") + ) { + throw new Error("profiled Gateway run omitted its durable Tailscale attribution"); + } + } else if (context.assurance.some((item) => item.kind === "durable-profile")) { + throw new Error("profileless Gateway run fabricated durable profile assurance"); + } +} + function findLocalRunId(gateway: Awaited>) { const stateDir = gateway.runtimeEnv.OPENCLAW_STATE_DIR; if (!stateDir) { @@ -198,6 +464,42 @@ function inspectExecutionIdentityStorage(gateway: Awaited>, + sessionKey: string, +) { + const stateDir = gateway.runtimeEnv.OPENCLAW_STATE_DIR; + const agentId = sessionKey.split(":")[1]; + if (!stateDir || !agentId) { + throw new Error("QA Gateway did not expose the session creator database owner"); + } + const database = new DatabaseSync( + path.join(stateDir, "agents", agentId, "agent", "openclaw-agent.sqlite"), + { readOnly: true }, + ); + try { + const row = database + .prepare( + "SELECT created_actor_type, created_actor_id, entry_json FROM session_nodes WHERE session_key = ?", + ) + .get(sessionKey) as + | { created_actor_id: string | null; created_actor_type: string | null; entry_json: string } + | undefined; + if (!row) { + throw new Error(`persisted session creator row is missing: ${sessionKey}`); + } + const entry = parseJson(row.entry_json, `persisted session ${sessionKey}`); + const actor = isRecord(entry) && isRecord(entry.createdActor) ? entry.createdActor : undefined; + return { + id: row.created_actor_id, + labelPersisted: actor ? Object.hasOwn(actor, "label") : false, + type: row.created_actor_type, + }; + } finally { + database.close(); + } +} + async function runLocalTurn( gateway: Awaited>, message: string, @@ -246,6 +548,17 @@ function findRunExecutions( } } +function assertPersistedContextBytes( + gateway: Awaited>, + runId: string, + expectedContext: string, +): void { + const rows = findRunExecutions(gateway, runId); + if (rows.length !== 1 || rows[0]?.context_json !== expectedContext) { + throw new Error(`RPC context bytes differ from persisted bytes: ${runId}`); + } +} + async function runRepeatedIngressTurns( gateway: Awaited>, repoRoot: string, @@ -291,8 +604,10 @@ async function runRepeatedIngressTurns( async function runProof(options: ProducerOptions): Promise { const mock = await startQaMockOpenAiServer(); + let fakeTailscale: Awaited> | undefined; let gateway: Awaited> | undefined; try { + fakeTailscale = await createFakeTailscaleBinary(); gateway = await startQaGatewayChild({ repoRoot: options.repoRoot, useRepoCli: true, @@ -300,20 +615,33 @@ async function runProof(options: ProducerOptions): Promise { providerMode: "mock-openai", transportBaseUrl: "http://127.0.0.1", controlUiEnabled: false, + mutateConfig: (cfg) => ({ + ...cfg, + gateway: { + ...cfg.gateway, + auth: { ...cfg.gateway?.auth, allowTailscale: true }, + }, + }), + runtimeEnvPatch: { + PATH: `${fakeTailscale.binaryDir}${path.delimiter}${process.env.PATH ?? ""}`, + }, + }); + await gateway.restartAfterStateMutation(async () => { + await runLocalTurn(gateway!, "Reply exactly: IDENTITY-DISABLED-FRESH"); }); - await runLocalTurn(gateway, "Reply exactly: IDENTITY-DISABLED-FRESH"); if (inspectExecutionIdentityStorage(gateway).tablePresent) { throw new Error("fresh-install default unexpectedly created execution identity storage"); } - await gateway.restartAfterStateMutation(async () => {}); - await runLocalTurn(gateway, "Reply exactly: IDENTITY-DISABLED-UPGRADE"); + await gateway.restartAfterStateMutation(async () => { + await runLocalTurn(gateway!, "Reply exactly: IDENTITY-DISABLED-UPGRADE"); + }); if (inspectExecutionIdentityStorage(gateway).tablePresent) { throw new Error("existing-install restart unexpectedly created execution identity storage"); } await gateway.restartAfterStateMutation(async ({ configPath }) => { await updateExecutionIdentityConfig(configPath, { executionIdentity: true }); + await runLocalTurn(gateway!, "Reply exactly: IDENTITY-INSPECTION-OK"); }); - await runLocalTurn(gateway, "Reply exactly: IDENTITY-INSPECTION-OK"); const runId = findLocalRunId(gateway); const beforeText = await gateway.runCli(["audit", "--run", runId, "--explain"]); assertTextProjection(beforeText); @@ -323,10 +651,150 @@ async function runProof(options: ProducerOptions): Promise { ) as AuditRunInspectResult; assertJsonProjection(before, runId); const beforeContext = normalizedContextJson(before); + assertPersistedContextBytes(gateway, runId, beforeContext); + + const profilelessSessionKey = `agent:qa:i1-profileless-${randomUUID()}`; + const profilelessStarted = (await gateway.call("agent", { + sessionKey: profilelessSessionKey, + message: "Reply exactly: I1-PROFILELESS", + deliver: false, + idempotencyKey: randomUUID(), + })) as { runId?: unknown; status?: unknown }; + if (profilelessStarted.status !== "accepted" || typeof profilelessStarted.runId !== "string") { + throw new Error( + `profileless Gateway run did not start: ${JSON.stringify(profilelessStarted)}`, + ); + } + const profilelessTerminal = (await gateway.call("agent.wait", { + runId: profilelessStarted.runId, + timeoutMs: 60_000, + })) as { status?: unknown }; + if (profilelessTerminal.status !== "ok") { + throw new Error( + `profileless Gateway run did not finish: ${JSON.stringify(profilelessTerminal)}`, + ); + } + const profilelessRunId = profilelessStarted.runId; + + const device = loadOrCreateDeviceIdentity({ + path: path.join(gateway.tempRoot, "i1-profiled-device.sqlite"), + }); + const tailscaleHeaders = { + "tailscale-user-login": "operator@example.com", + "tailscale-user-name": "Operator", + "x-forwarded-for": "100.64.0.11", + "x-forwarded-host": "gateway.qa.test", + "x-forwarded-proto": "https", + }; + let profiled = await connectRawDevice({ + device, + headers: tailscaleHeaders, + wsUrl: gateway.wsUrl, + }); + if (!profiled.connected) { + await approveDeviceIfNeeded(gateway, device.deviceId); + await closeRawGatewayClient(profiled.client); + profiled = await connectRawDevice({ + device, + headers: tailscaleHeaders, + wsUrl: gateway.wsUrl, + }); + } + if (!profiled.connected) { + throw new Error( + `Tailscale-profiled Gateway client failed: ${JSON.stringify(profiled.client.frames)}`, + ); + } + const profiledSessionKey = `agent:qa:i1-profiled-${randomUUID()}`; + const profiledRunId = await runGatewayTurn( + profiled.client, + "Reply exactly: I1-PROFILED", + profiledSessionKey, + ); + await closeRawGatewayClient(profiled.client); + + const profilelessText = await gateway.runCli(["audit", "--run", profilelessRunId, "--explain"]); + const profiledText = await gateway.runCli(["audit", "--run", profiledRunId, "--explain"]); + assertTextProjection(profilelessText); + assertTextProjection(profiledText); + if ( + !profilelessText.includes("Invoker [absent]") || + !profilelessText.includes("Represented subject [absent]") || + profilelessText.includes("Operator") + ) { + throw new Error("profileless text inspection fabricated an operator subject"); + } + if ( + !profiledText.includes("Invoker [present]") || + !profiledText.includes("Represented subject [absent]") + ) { + throw new Error( + `profiled text inspection omitted durable operator attribution: ${profiledText}`, + ); + } + const profilelessBefore = parseJson( + await gateway.runCli(["audit", "--run", profilelessRunId, "--explain", "--json"]), + "profileless Gateway inspection", + ) as AuditRunInspectResult; + const profiledBefore = parseJson( + await gateway.runCli(["audit", "--run", profiledRunId, "--explain", "--json"]), + "profiled Gateway inspection", + ) as AuditRunInspectResult; + assertGatewayIdentityProjection(profilelessBefore, { + coverage: "unattributed", + invoker: "absent", + }); + assertGatewayIdentityProjection(profiledBefore, { + coverage: "attribution-only", + invoker: "present", + }); + const profilelessContext = normalizedContextJson(profilelessBefore); + const profiledContext = normalizedContextJson(profiledBefore); + assertPersistedContextBytes(gateway, profilelessRunId, profilelessContext); + assertPersistedContextBytes(gateway, profiledRunId, profiledContext); + + const listed = (await gateway.call("sessions.list", {})) as { + sessions?: Array<{ + key?: string; + createdActor?: { id?: string; label?: string; type?: string }; + }>; + }; + const profilelessSession = listed.sessions?.find( + (session) => session.key === profilelessSessionKey, + ); + const profiledSession = listed.sessions?.find((session) => session.key === profiledSessionKey); + if (profilelessSession?.createdActor !== undefined) { + throw new Error("profileless Gateway session fabricated a human creator"); + } + const profilelessCreator = inspectPersistedSessionCreator(gateway, profilelessSessionKey); + if ( + profilelessCreator.type !== null || + profilelessCreator.id !== null || + profilelessCreator.labelPersisted + ) { + throw new Error("profileless Gateway session persisted a fabricated creator"); + } + if ( + profiledSession?.createdActor?.type !== "human" || + !profiledSession.createdActor.id || + profiledSession.createdActor.label !== "Operator" + ) { + throw new Error("profiled Gateway session lost its current profile display projection"); + } + const profiledCreator = inspectPersistedSessionCreator(gateway, profiledSessionKey); + if ( + profiledCreator.type !== "human" || + profiledCreator.id !== profiledSession.createdActor.id || + profiledCreator.labelPersisted + ) { + throw new Error("profiled Gateway session did not persist only its authenticated profile id"); + } const repeatedRunId = `identity-repeated-${randomUUID()}`; + let repeatedRows: ReturnType = []; + const repeatedBeforeRestart = new Map(); await runRepeatedIngressTurns(gateway, options.repoRoot, repeatedRunId); - const repeatedRows = findRunExecutions(gateway, repeatedRunId); + repeatedRows = findRunExecutions(gateway, repeatedRunId); if ( repeatedRows.length !== 2 || new Set(repeatedRows.map((row) => row.execution_id)).size !== 2 || @@ -350,7 +818,6 @@ async function runProof(options: ProducerOptions): Promise { if (discovery.identity.state !== "ambiguous" || discovery.identity.candidates.length !== 2) { throw new Error("repeated same-session run was not reported as two ambiguous executions"); } - const repeatedBeforeRestart = new Map(); for (const row of repeatedRows) { const text = await gateway.runCli(["audit", "--execution", row.execution_id, "--explain"]); assertTextProjection(text); @@ -389,6 +856,19 @@ async function runProof(options: ProducerOptions): Promise { if (afterContext !== beforeContext) { throw new Error("normalized execution identity context bytes changed across Gateway restart"); } + for (const [gatewayRunId, expectedContext, expectedIdentity] of [ + [profilelessRunId, profilelessContext, { coverage: "unattributed", invoker: "absent" }], + [profiledRunId, profiledContext, { coverage: "attribution-only", invoker: "present" }], + ] as const) { + const afterGateway = parseJson( + await gateway.runCli(["audit", "--run", gatewayRunId, "--explain", "--json"]), + `post-restart Gateway run ${gatewayRunId}`, + ) as AuditRunInspectResult; + assertGatewayIdentityProjection(afterGateway, expectedIdentity); + if (normalizedContextJson(afterGateway) !== expectedContext) { + throw new Error(`Gateway execution changed across restart: ${gatewayRunId}`); + } + } for (const [executionId, expectedContext] of repeatedBeforeRestart) { const afterExact = parseJson( await gateway.runCli(["audit", "--execution", executionId, "--explain", "--json"]), @@ -404,8 +884,8 @@ async function runProof(options: ProducerOptions): Promise { enabled: false, executionIdentity: true, }); + await runLocalTurn(gateway!, "Reply exactly: IDENTITY-DISABLED-GLOBAL"); }); - await runLocalTurn(gateway, "Reply exactly: IDENTITY-DISABLED-GLOBAL"); if (inspectExecutionIdentityStorage(gateway).rowCount !== retainedBeforeGlobalDisable) { throw new Error("global audit disable unexpectedly retained a new execution context"); } @@ -424,6 +904,13 @@ async function runProof(options: ProducerOptions): Promise { `${JSON.stringify( { runId, + gatewayRuns: { + profiled: { runId: profiledRunId, contextSha256: sha256(profiledContext) }, + profileless: { + runId: profilelessRunId, + contextSha256: sha256(profilelessContext), + }, + }, repeatedRunId, repeatedExecutions: repeatedRows.map((row) => ({ executionId: row.execution_id, @@ -450,10 +937,12 @@ async function runProof(options: ProducerOptions): Promise { )}\n`, "utf8", ); - return `local run=${runId}; repeated run=${repeatedRunId} executions=${repeatedRows.map((row) => row.execution_id).join(",")}; Gateway pid=${gateway.pid ?? "unknown"}; text+JSON exact selection passed before/after replacement; normalized context sha256=${sha256(beforeContext)}`; + const repeatedDetails = `repeated run=${repeatedRunId} executions=${repeatedRows.map((row) => row.execution_id).join(",")}; exact selection passed`; + return `local run=${runId}; profiled Gateway run=${profiledRunId}; profileless Gateway run=${profilelessRunId}; ${repeatedDetails}; Gateway pid=${gateway.pid ?? "unknown"}; text+JSON and persisted bytes passed before/after replacement; normalized context sha256=${sha256(beforeContext)}`; } finally { await gateway?.stop().catch(() => undefined); await mock.stop(); + await fakeTailscale?.cleanup(); } } From d44f70eb4bd528d8a69ff2a7806304d791e9e489 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 12 Aug 2026 02:01:33 -0700 Subject: [PATCH 077/165] feat(pairing): one-paste device pairing via oc-pair setup links (#120768) * feat(pairing): one-paste device pairing via oc-pair setup links Implements milestone 3 from docs/plan/runners.md. * fix(pairing): sign bootstrap handshake, keep URL candidates, wire pairing countdown * test(gateway): update client callsite guard * fix(pairing): preserve setup URL context paths * fix(ui): keep pairing help aligned with setup mode * fix(pairing): isolate bootstrap credentials * perf(ui): keep one-paste pairing within bundle budget * refactor(pairing): isolate native pair URL prefix parsing * fix(pairing): preserve candidate lifecycle state * fix(pairing): retire shared credentials after bootstrap * fix(pairing): apply rotated manifest through client owner * test(pairing): prove bootstrap retirement across reconnect * fix(pairing): preserve native gateway context paths * fix(pairing): carry native context paths through reconnect * fix(ios): preserve encoded gateway context path * chore(plugin-sdk): refresh pairing API baselines --- apps/.i18n/native-source.json | 384 +++++++++--------- .../java/ai/openclaw/app/MainViewModel.kt | 2 + .../main/java/ai/openclaw/app/NodeRuntime.kt | 2 + .../openclaw/app/gateway/GatewayEndpoint.kt | 58 ++- .../openclaw/app/gateway/GatewayRegistry.kt | 2 + .../ai/openclaw/app/gateway/GatewaySession.kt | 14 +- .../openclaw/app/ui/GatewayConfigResolver.kt | 40 +- .../app/gateway/GatewayRegistryStoreTest.kt | 32 ++ .../GatewaySessionInvokeTimeoutTest.kt | 31 ++ .../app/ui/GatewayConfigResolverTest.kt | 72 +++- apps/ios/Sources/Design/SettingsProTab.swift | 1 + .../Design/SettingsProTabActions.swift | 16 +- .../Design/SettingsProTabSections.swift | 1 + ...wayConnectionController+Capabilities.swift | 22 +- ...tewayConnectionController+ManualAuth.swift | 15 +- .../Gateway/GatewayConnectionController.swift | 41 +- .../Gateway/GatewaySettingsStore.swift | 28 ++ .../Onboarding/OnboardingWizardView.swift | 11 +- .../GatewayConnectionControllerTests.swift | 73 ++++ .../ios/Tests/GatewaySettingsStoreTests.swift | 2 + .../Sources/OpenClawKit/DeepLinks.swift | 121 +++++- .../OpenClawProtocol/GatewayModels.swift | 6 +- .../DeepLinksSecurityTests.swift | 74 +++- .../agent-harness-runtime.json | 2 +- .../agent-harness.json | 2 +- .../plugin-sdk-api-baseline/channel-core.json | 2 +- .../channel-entry-contract.json | 2 +- .../channel-message.json | 2 +- .../channel-outbound.json | 2 +- .../channel-plugin-common.json | 2 +- .../plugin-sdk-api-baseline/core.json | 2 +- .../plugin-sdk-api-baseline/discord.json | 2 +- .../gateway-runtime.json | 2 +- .../inbound-reply-dispatch.json | 2 +- .../meeting-runtime.json | 2 +- .../plugin-sdk-api-baseline/plugin-entry.json | 2 +- .../plugin-runtime.json | 2 +- .../provider-catalog-runtime.json | 2 +- .../plugin-sdk-api-baseline/tool-plugin.json | 2 +- .../webhook-ingress.json | 2 +- docs/channels/pairing.md | 2 +- docs/cli/node.md | 15 + docs/gateway/pairing.md | 22 + docs/nodes/index.md | 16 +- docs/platforms/ios.md | 2 +- docs/web/control-ui.md | 2 +- .../src/browser-device-auth.test.ts | 14 +- packages/gateway-client/src/client.ts | 12 + packages/gateway-client/src/connect-auth.ts | 6 +- .../gateway-protocol/src/schema/devices.ts | 1 + src/cli/node-cli/gateway-options.test.ts | 62 +++ src/cli/node-cli/gateway-options.ts | 76 +++- src/cli/node-cli/register.test.ts | 81 ++++ src/cli/node-cli/register.ts | 23 +- src/cli/qr-cli.test.ts | 5 + src/cli/qr-cli.ts | 5 + src/cli/resume-cli.test.ts | 51 +++ src/gateway/call.test.ts | 3 + src/gateway/client-callsites.guard.test.ts | 2 +- src/gateway/client.test.ts | 71 ++++ src/gateway/minimal-gateway.test-helpers.ts | 63 +-- src/gateway/probe.test.ts | 1 + src/gateway/server-kernel-request-runtime.ts | 2 + .../server-methods/device-pair-setup.test.ts | 7 + .../server-methods/device-pair-setup.ts | 2 + src/gateway/server-methods/shared-types.ts | 2 + src/gateway/server-request-context.ts | 2 + .../gateway-candidate-connection.test.ts | 179 ++++++++ src/node-host/gateway-candidate-connection.ts | 152 +++++++ src/node-host/runner.test.ts | 89 +++- src/node-host/runner.ts | 101 ++--- src/pairing/setup-code.test.ts | 77 +++- src/pairing/setup-code.ts | 104 ++++- ui/src/app/app-host-pairing-access.test.ts | 105 +++-- ui/src/app/app-host.ts | 5 + ui/src/app/app-shell-view.ts | 47 ++- ui/src/app/lazy-custom-element.ts | 8 + ui/src/app/overlays-types.ts | 41 ++ ui/src/app/overlays.ts | 46 +-- ui/src/app/update-overlay-helpers.ts | 13 +- ui/src/components/exec-approval-card.ts | 8 +- ui/src/components/exec-approval.ts | 4 +- ui/src/e2e/mobile-pairing.e2e.test.ts | 34 +- ui/src/i18n/locales/en.ts | 13 +- ui/src/lib/device-pair-setup.test.ts | 18 +- ui/src/lib/device-pair-setup.ts | 39 +- ui/src/lib/format.ts | 6 + .../chat/components/chat-question-card.ts | 9 +- ui/src/pages/config/security.test.ts | 4 +- ui/src/pages/devices/view-pairing.test.ts | 83 ++++ ui/src/pages/devices/view-pairing.ts | 154 ++++--- ui/src/styles/components.css | 6 + 92 files changed, 2432 insertions(+), 545 deletions(-) create mode 100644 src/cli/node-cli/gateway-options.test.ts create mode 100644 src/node-host/gateway-candidate-connection.test.ts create mode 100644 src/node-host/gateway-candidate-connection.ts create mode 100644 ui/src/app/overlays-types.ts create mode 100644 ui/src/pages/devices/view-pairing.test.ts diff --git a/apps/.i18n/native-source.json b/apps/.i18n/native-source.json index b19cbf254868..5c6df64503fa 100644 --- a/apps/.i18n/native-source.json +++ b/apps/.i18n/native-source.json @@ -1667,7 +1667,7 @@ }, { "kind": "ui-call", - "line": 8980, + "line": 8982, "path": "apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt", "source": "Dream", "surface": "android", @@ -3459,7 +3459,7 @@ }, { "kind": "ui-call", - "line": 93, + "line": 96, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Public gateways require wss:// or Tailscale Serve. ws:// is allowed for localhost, .local hosts, the Android emulator, and private LAN IPs.", "surface": "android", @@ -3467,7 +3467,7 @@ }, { "kind": "ui-call", - "line": 98, + "line": 101, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Use a private LAN IP for local setup, or enable Tailscale Serve / expose a wss:// gateway URL for remote access.", "surface": "android", @@ -3475,23 +3475,23 @@ }, { "kind": "conditional-branch", - "line": 253, + "line": 267, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", - "source": "${if (tls) \"https\" else \"http\"}://$displayHost", + "source": "${if (tls) \"https\" else \"http\"}://$displayHost$displayPath", "surface": "android", - "id": "native.android.ff5abe2418979715" + "id": "native.android.73109af9b97b61eb" }, { "kind": "conditional-branch", - "line": 255, + "line": 269, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", - "source": "${if (tls) \"https\" else \"http\"}://$displayHost:$port", + "source": "${if (tls) \"https\" else \"http\"}://$displayHost:$port$displayPath", "surface": "android", - "id": "native.android.28e58e1bd98e08ab" + "id": "native.android.6c4a0216a29d5921" }, { "kind": "ui-call", - "line": 322, + "line": 343, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Setup code points to an insecure remote gateway. $remoteGatewaySecurityRule $remoteGatewaySecurityFix", "surface": "android", @@ -3499,7 +3499,7 @@ }, { "kind": "ui-call", - "line": 328, + "line": 349, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "QR code points to an insecure remote gateway. $remoteGatewaySecurityRule $remoteGatewaySecurityFix", "surface": "android", @@ -3507,7 +3507,7 @@ }, { "kind": "ui-call", - "line": 334, + "line": 355, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "$remoteGatewaySecurityRule $remoteGatewaySecurityFix", "surface": "android", @@ -3515,7 +3515,7 @@ }, { "kind": "ui-call", - "line": 343, + "line": 364, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Setup code uses an IPv6 zone ID. Use an unscoped IPv6 address or a LAN hostname.", "surface": "android", @@ -3523,7 +3523,7 @@ }, { "kind": "ui-call", - "line": 345, + "line": 366, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "QR code uses an IPv6 zone ID. Use an unscoped IPv6 address or a LAN hostname.", "surface": "android", @@ -3531,7 +3531,7 @@ }, { "kind": "ui-call", - "line": 347, + "line": 368, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "IPv6 zone IDs are not supported. Use an unscoped IPv6 address or a LAN hostname.", "surface": "android", @@ -3539,7 +3539,7 @@ }, { "kind": "ui-call", - "line": 351, + "line": 372, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Setup code has invalid gateway URL.", "surface": "android", @@ -3547,7 +3547,7 @@ }, { "kind": "ui-call", - "line": 352, + "line": 373, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "QR code did not contain a valid setup code.", "surface": "android", @@ -3555,7 +3555,7 @@ }, { "kind": "ui-call", - "line": 353, + "line": 374, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Enter a valid manual endpoint to connect.", "surface": "android", @@ -3563,7 +3563,7 @@ }, { "kind": "ui-call", - "line": 493, + "line": 514, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Secure connection is required for this host.", "surface": "android", @@ -3571,7 +3571,7 @@ }, { "kind": "ui-call", - "line": 495, + "line": 516, "path": "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt", "source": "Use only on a trusted private network.", "surface": "android", @@ -21835,7 +21835,7 @@ }, { "kind": "ui-modifier", - "line": 156, + "line": 157, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Settings", "surface": "apple", @@ -21843,7 +21843,7 @@ }, { "kind": "ui-modifier", - "line": 264, + "line": 265, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Scan QR Code", "surface": "apple", @@ -21851,7 +21851,7 @@ }, { "kind": "ui-modifier", - "line": 286, + "line": 287, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Reset Onboarding?", "surface": "apple", @@ -21859,7 +21859,7 @@ }, { "kind": "ui-call", - "line": 290, + "line": 291, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Reset", "surface": "apple", @@ -21867,7 +21867,7 @@ }, { "kind": "ui-call", - "line": 298, + "line": 299, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "This disconnects, clears saved gateway credentials, and reopens onboarding.", "surface": "apple", @@ -21875,7 +21875,7 @@ }, { "kind": "ui-modifier", - "line": 302, + "line": 303, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "QR Scanner Unavailable", "surface": "apple", @@ -21883,7 +21883,7 @@ }, { "kind": "ui-call", - "line": 311, + "line": 312, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "OK", "surface": "apple", @@ -21891,7 +21891,7 @@ }, { "kind": "ui-localized-call", - "line": 320, + "line": 321, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Forget %@?", "surface": "apple", @@ -21899,7 +21899,7 @@ }, { "kind": "ui-localized-call", - "line": 321, + "line": 322, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "gateway", "surface": "apple", @@ -21907,7 +21907,7 @@ }, { "kind": "ui-call", - "line": 336, + "line": 337, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Forget Gateway", "surface": "apple", @@ -21915,7 +21915,7 @@ }, { "kind": "ui-call", - "line": 342, + "line": 343, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Cancel", "surface": "apple", @@ -21923,7 +21923,7 @@ }, { "kind": "ui-localized-call", - "line": 350, + "line": 351, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "This removes saved credentials, device access, TLS trust, and cached chats for this gateway.", "surface": "apple", @@ -21931,7 +21931,7 @@ }, { "kind": "ui-call", - "line": 404, + "line": 405, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Enable OpenClaw Hosted Push Relay?", "surface": "apple", @@ -21939,7 +21939,7 @@ }, { "kind": "ui-call", - "line": 418, + "line": 419, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Continue", "surface": "apple", @@ -21947,7 +21947,7 @@ }, { "kind": "ui-call", - "line": 426, + "line": 427, "path": "apps/ios/Sources/Design/SettingsProTab.swift", "source": "Not Now", "surface": "apple", @@ -22123,7 +22123,7 @@ }, { "kind": "ui-localized-call", - "line": 329, + "line": 338, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "TLS", "surface": "apple", @@ -22131,7 +22131,7 @@ }, { "kind": "ui-localized-call", - "line": 329, + "line": 338, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "plain", "surface": "apple", @@ -22139,7 +22139,7 @@ }, { "kind": "ui-localized-call", - "line": 332, + "line": 341, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Setup link loaded for %@:%@ (%@). Tap Connect to apply.", "surface": "apple", @@ -22147,7 +22147,7 @@ }, { "kind": "ui-localized-call", - "line": 343, + "line": 352, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Paste a setup code to continue.", "surface": "apple", @@ -22155,7 +22155,7 @@ }, { "kind": "ui-localized-call", - "line": 358, + "line": 367, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Setup code not recognized or uses an insecure ws:// gateway URL.", "surface": "apple", @@ -22163,7 +22163,7 @@ }, { "kind": "ui-localized-call", - "line": 404, + "line": 414, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Opening QR scanner...", "surface": "apple", @@ -22171,7 +22171,7 @@ }, { "kind": "ui-localized-call", - "line": 410, + "line": 420, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "QR loaded. Closing scanner...", "surface": "apple", @@ -22179,7 +22179,7 @@ }, { "kind": "ui-localized-call", - "line": 440, + "line": 450, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Apple Review demo mode enabled.", "surface": "apple", @@ -22187,7 +22187,7 @@ }, { "kind": "ui-localized-call", - "line": 491, + "line": 501, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Failed: host required", "surface": "apple", @@ -22195,7 +22195,7 @@ }, { "kind": "ui-localized-call", - "line": 499, + "line": 509, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Failed: invalid port", "surface": "apple", @@ -22203,7 +22203,7 @@ }, { "kind": "ui-localized-call", - "line": 557, + "line": 568, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Tailscale is off on this device. Turn it on, then try again.", "surface": "apple", @@ -22211,7 +22211,7 @@ }, { "kind": "ui-localized-call", - "line": 934, + "line": 947, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Gateway", "surface": "apple", @@ -22219,7 +22219,7 @@ }, { "kind": "ui-localized-call", - "line": 935, + "line": 948, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "OpenClaw", "surface": "apple", @@ -22227,7 +22227,7 @@ }, { "kind": "ui-localized-call", - "line": 936, + "line": 949, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Apple Watch", "surface": "apple", @@ -22235,7 +22235,7 @@ }, { "kind": "ui-localized-call", - "line": 937, + "line": 950, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Approvals", "surface": "apple", @@ -22243,7 +22243,7 @@ }, { "kind": "ui-localized-call", - "line": 938, + "line": 951, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Permissions", "surface": "apple", @@ -22251,7 +22251,7 @@ }, { "kind": "ui-localized-call", - "line": 939, + "line": 952, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Channels", "surface": "apple", @@ -22259,7 +22259,7 @@ }, { "kind": "ui-localized-call", - "line": 940, + "line": 953, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Skills", "surface": "apple", @@ -22267,7 +22267,7 @@ }, { "kind": "ui-localized-call", - "line": 941, + "line": 954, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Voice & Talk", "surface": "apple", @@ -22275,7 +22275,7 @@ }, { "kind": "ui-localized-call", - "line": 942, + "line": 955, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Diagnostics", "surface": "apple", @@ -22283,7 +22283,7 @@ }, { "kind": "ui-localized-call", - "line": 943, + "line": 956, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Privacy", "surface": "apple", @@ -22291,7 +22291,7 @@ }, { "kind": "ui-localized-call", - "line": 945, + "line": 958, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Licenses", "surface": "apple", @@ -22299,7 +22299,7 @@ }, { "kind": "ui-localized-call", - "line": 946, + "line": 959, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "About", "surface": "apple", @@ -22307,7 +22307,7 @@ }, { "kind": "ui-localized-call", - "line": 953, + "line": 966, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Preparing one-time setup…", "surface": "apple", @@ -22315,7 +22315,7 @@ }, { "kind": "ui-localized-call", - "line": 958, + "line": 971, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Setup sent. Open OpenClaw on the watch to connect.", "surface": "apple", @@ -22323,7 +22323,7 @@ }, { "kind": "ui-localized-call", - "line": 960, + "line": 973, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Setup queued for the watch. Open OpenClaw before the code expires.", "surface": "apple", @@ -22331,7 +22331,7 @@ }, { "kind": "ui-localized-call", - "line": 1050, + "line": 1064, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "This gateway is on your tailnet. Turn on Tailscale on this device, then tap Connect.", "surface": "apple", @@ -22339,7 +22339,7 @@ }, { "kind": "ui-localized-call", - "line": 1057, + "line": 1071, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Pairing required. Run /pair approve in your OpenClaw chat, then connect again.", "surface": "apple", @@ -22347,7 +22347,7 @@ }, { "kind": "ui-localized-call", - "line": 1060, + "line": 1074, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Secure handshake failed. Check Tailscale, then connect again.", "surface": "apple", @@ -22355,7 +22355,7 @@ }, { "kind": "ui-localized-call", - "line": 1069, + "line": 1083, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Connection timed out. Make sure Tailscale is connected, then try again.", "surface": "apple", @@ -22363,7 +22363,7 @@ }, { "kind": "ui-localized-call", - "line": 1073, + "line": 1087, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Connected, but some controls are restricted for nodes. This is expected.", "surface": "apple", @@ -22371,7 +22371,7 @@ }, { "kind": "ui-localized-call", - "line": 1080, + "line": 1094, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Setup code applied. Connecting...", "surface": "apple", @@ -22379,7 +22379,7 @@ }, { "kind": "ui-localized-call", - "line": 1081, + "line": 1095, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Checking gateway reachability...", "surface": "apple", @@ -22387,7 +22387,7 @@ }, { "kind": "ui-localized-call", - "line": 1082, + "line": 1096, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "QR loaded. Connecting to %@:%@...", "surface": "apple", @@ -22395,7 +22395,7 @@ }, { "kind": "ui-localized-call", - "line": 1145, + "line": 1159, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Not loaded", "surface": "apple", @@ -22403,7 +22403,7 @@ }, { "kind": "ui-localized-call", - "line": 1148, + "line": 1162, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Configured", "surface": "apple", @@ -22411,7 +22411,7 @@ }, { "kind": "ui-localized-call", - "line": 1149, + "line": 1163, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Not configured", "surface": "apple", @@ -22419,7 +22419,7 @@ }, { "kind": "ui-localized-call", - "line": 1156, + "line": 1170, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Not active", "surface": "apple", @@ -22427,7 +22427,7 @@ }, { "kind": "ui-localized-call", - "line": 1192, + "line": 1206, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Apple Review demo mode", "surface": "apple", @@ -22435,7 +22435,7 @@ }, { "kind": "ui-localized-call", - "line": 1195, + "line": 1209, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Connected", "surface": "apple", @@ -22443,7 +22443,7 @@ }, { "kind": "ui-localized-call", - "line": 1201, + "line": 1215, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "offline", "surface": "apple", @@ -22451,7 +22451,7 @@ }, { "kind": "ui-localized-call", - "line": 1201, + "line": 1215, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "online", "surface": "apple", @@ -22459,7 +22459,7 @@ }, { "kind": "ui-localized-call", - "line": 1219, + "line": 1233, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Live gateway requests are disabled in demo mode.", "surface": "apple", @@ -22467,7 +22467,7 @@ }, { "kind": "ui-localized-call", - "line": 1223, + "line": 1237, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Foreground approvals still appear while OpenClaw is connected.", "surface": "apple", @@ -22475,7 +22475,7 @@ }, { "kind": "ui-localized-call", - "line": 1226, + "line": 1240, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Gateway requests will appear here.", "surface": "apple", @@ -22483,7 +22483,7 @@ }, { "kind": "ui-localized-call", - "line": 1227, + "line": 1241, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Connect to the gateway.", "surface": "apple", @@ -22491,7 +22491,7 @@ }, { "kind": "ui-localized-call", - "line": 1231, + "line": 1245, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Demo mode only", "surface": "apple", @@ -22499,7 +22499,7 @@ }, { "kind": "ui-localized-call", - "line": 1238, + "line": 1252, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "loaded", "surface": "apple", @@ -22507,7 +22507,7 @@ }, { "kind": "ui-localized-call", - "line": 1239, + "line": 1253, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "missing", "surface": "apple", @@ -22515,7 +22515,7 @@ }, { "kind": "ui-localized-call", - "line": 1248, + "line": 1262, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Waiting for gateway", "surface": "apple", @@ -22523,7 +22523,7 @@ }, { "kind": "ui-localized-call", - "line": 1265, + "line": 1279, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "1 waiting", "surface": "apple", @@ -22531,7 +22531,7 @@ }, { "kind": "ui-localized-call", - "line": 1268, + "line": 1282, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "%@ waiting", "surface": "apple", @@ -22539,7 +22539,7 @@ }, { "kind": "ui-localized-call", - "line": 1279, + "line": 1293, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Review gateway action", "surface": "apple", @@ -22547,7 +22547,7 @@ }, { "kind": "ui-localized-call", - "line": 1281, + "line": 1295, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Agent: %@", "surface": "apple", @@ -22555,7 +22555,7 @@ }, { "kind": "ui-localized-call", - "line": 1290, + "line": 1304, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Resolving", "surface": "apple", @@ -22563,7 +22563,7 @@ }, { "kind": "ui-localized-call", - "line": 1291, + "line": 1305, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "High", "surface": "apple", @@ -22571,7 +22571,7 @@ }, { "kind": "ui-localized-call", - "line": 1297, + "line": 1311, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Permission can be saved", "surface": "apple", @@ -22579,7 +22579,7 @@ }, { "kind": "ui-localized-call", - "line": 1298, + "line": 1312, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "One-time approval", "surface": "apple", @@ -22587,7 +22587,7 @@ }, { "kind": "ui-localized-call", - "line": 1301, + "line": 1315, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Medium", "surface": "apple", @@ -22595,7 +22595,7 @@ }, { "kind": "ui-localized-call", - "line": 1302, + "line": 1316, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Review", "surface": "apple", @@ -22603,7 +22603,7 @@ }, { "kind": "ui-localized-call", - "line": 1308, + "line": 1322, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Talk + Wake", "surface": "apple", @@ -22611,7 +22611,7 @@ }, { "kind": "ui-localized-call", - "line": 1309, + "line": 1323, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Talk on", "surface": "apple", @@ -22619,7 +22619,7 @@ }, { "kind": "ui-localized-call", - "line": 1310, + "line": 1324, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Wake on", "surface": "apple", @@ -22627,7 +22627,7 @@ }, { "kind": "ui-localized-call", - "line": 1311, + "line": 1325, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Off", "surface": "apple", @@ -22635,7 +22635,7 @@ }, { "kind": "ui-localized-call", - "line": 1315, + "line": 1329, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "demo", "surface": "apple", @@ -22643,7 +22643,7 @@ }, { "kind": "ui-localized-call", - "line": 1316, + "line": 1330, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "ready", "surface": "apple", @@ -22651,7 +22651,7 @@ }, { "kind": "ui-localized-call", - "line": 1317, + "line": 1331, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "check", "surface": "apple", @@ -22659,7 +22659,7 @@ }, { "kind": "ui-localized-call", - "line": 1318, + "line": 1332, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "partial", "surface": "apple", @@ -22667,7 +22667,7 @@ }, { "kind": "ui-localized-call", - "line": 1322, + "line": 1336, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "pending", "surface": "apple", @@ -22675,7 +22675,7 @@ }, { "kind": "ui-localized-call", - "line": 1324, + "line": 1338, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "pass", "surface": "apple", @@ -22683,7 +22683,7 @@ }, { "kind": "ui-localized-call", - "line": 1335, + "line": 1349, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Requesting iOS location permission…", "surface": "apple", @@ -22691,7 +22691,7 @@ }, { "kind": "ui-localized-call", - "line": 1401, + "line": 1415, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "This build uses OpenClaw's hosted push relay at %@ for notification delivery data.", "surface": "apple", @@ -22699,7 +22699,7 @@ }, { "kind": "ui-localized-call", - "line": 1405, + "line": 1419, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "This build is not configured to use OpenClaw's hosted push relay.", "surface": "apple", @@ -22707,7 +22707,7 @@ }, { "kind": "ui-localized-call", - "line": 1410, + "line": 1424, "path": "apps/ios/Sources/Design/SettingsProTabActions.swift", "source": "Enabling this sends delivery data through OpenClaw's hosted push relay.", "surface": "apple", @@ -23595,7 +23595,7 @@ }, { "kind": "ui-call", - "line": 1343, + "line": 1344, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Auto-connect on launch", "surface": "apple", @@ -23603,7 +23603,7 @@ }, { "kind": "ui-call", - "line": 1344, + "line": 1345, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Gateway Auth Token", "surface": "apple", @@ -23611,7 +23611,7 @@ }, { "kind": "ui-call", - "line": 1345, + "line": 1346, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Gateway Password", "surface": "apple", @@ -23619,7 +23619,7 @@ }, { "kind": "ui-call", - "line": 1350, + "line": 1351, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Custom Headers", "surface": "apple", @@ -23627,7 +23627,7 @@ }, { "kind": "ui-call", - "line": 1357, + "line": 1358, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Reset Onboarding", "surface": "apple", @@ -23635,7 +23635,7 @@ }, { "kind": "ui-call", - "line": 1387, + "line": 1388, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Voice Wake", "surface": "apple", @@ -23643,7 +23643,7 @@ }, { "kind": "ui-call", - "line": 1390, + "line": 1391, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Talk Mode", "surface": "apple", @@ -23651,7 +23651,7 @@ }, { "kind": "ui-call", - "line": 1398, + "line": 1399, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Speech Language", "surface": "apple", @@ -23659,7 +23659,7 @@ }, { "kind": "ui-call", - "line": 1405, + "line": 1406, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Speakerphone", "surface": "apple", @@ -23667,7 +23667,7 @@ }, { "kind": "ui-call", - "line": 1409, + "line": 1410, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Wake Words", "surface": "apple", @@ -23675,7 +23675,7 @@ }, { "kind": "ui-call", - "line": 1431, + "line": 1432, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Voice", "surface": "apple", @@ -23683,7 +23683,7 @@ }, { "kind": "ui-call", - "line": 1432, + "line": 1433, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Provider", "surface": "apple", @@ -23691,7 +23691,7 @@ }, { "kind": "ui-call", - "line": 1439, + "line": 1440, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Realtime Voice", "surface": "apple", @@ -23699,7 +23699,7 @@ }, { "kind": "ui-call", - "line": 1440, + "line": 1441, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Gateway Default", "surface": "apple", @@ -23707,7 +23707,7 @@ }, { "kind": "ui-call", - "line": 1447, + "line": 1448, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Voice Mode", "surface": "apple", @@ -23715,7 +23715,7 @@ }, { "kind": "ui-call", - "line": 1450, + "line": 1451, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Active Voice", "surface": "apple", @@ -23723,7 +23723,7 @@ }, { "kind": "ui-call", - "line": 1454, + "line": 1455, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Last Voice Issue", "surface": "apple", @@ -23731,7 +23731,7 @@ }, { "kind": "ui-call", - "line": 1456, + "line": 1457, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Transport", "surface": "apple", @@ -23739,7 +23739,7 @@ }, { "kind": "ui-call", - "line": 1459, + "line": 1460, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "API Key", "surface": "apple", @@ -23747,7 +23747,7 @@ }, { "kind": "ui-call", - "line": 1466, + "line": 1467, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Show Talk Control", "surface": "apple", @@ -23755,7 +23755,7 @@ }, { "kind": "ui-call", - "line": 1467, + "line": 1468, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Default Share Instruction", "surface": "apple", @@ -23763,7 +23763,7 @@ }, { "kind": "ui-call", - "line": 1474, + "line": 1475, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Run Share Self-Test", "surface": "apple", @@ -23771,7 +23771,7 @@ }, { "kind": "ui-call", - "line": 1493, + "line": 1494, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Apple Health", "surface": "apple", @@ -23779,7 +23779,7 @@ }, { "kind": "ui-call", - "line": 1501, + "line": 1502, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Discovery Debug Logs", "surface": "apple", @@ -23787,7 +23787,7 @@ }, { "kind": "ui-call", - "line": 1504, + "line": 1505, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Debug Screen Status", "surface": "apple", @@ -23795,7 +23795,7 @@ }, { "kind": "ui-call", - "line": 1508, + "line": 1509, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Discovery Logs", "surface": "apple", @@ -23803,7 +23803,7 @@ }, { "kind": "ui-call", - "line": 1516, + "line": 1517, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Device", "surface": "apple", @@ -23811,7 +23811,7 @@ }, { "kind": "ui-call", - "line": 1517, + "line": 1518, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Device Name", "surface": "apple", @@ -23819,7 +23819,7 @@ }, { "kind": "ui-call", - "line": 1519, + "line": 1520, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Instance ID", "surface": "apple", @@ -23827,7 +23827,7 @@ }, { "kind": "ui-localized-call", - "line": 1543, + "line": 1544, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "On", "surface": "apple", @@ -23835,7 +23835,7 @@ }, { "kind": "ui-localized-call", - "line": 1544, + "line": 1545, "path": "apps/ios/Sources/Design/SettingsProTabSections.swift", "source": "Off", "surface": "apple", @@ -25203,7 +25203,7 @@ }, { "kind": "ui-localized-call", - "line": 42, + "line": 46, "path": "apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift", "source": "Secure connection is required for this host.", "surface": "apple", @@ -25211,7 +25211,7 @@ }, { "kind": "ui-localized-call", - "line": 46, + "line": 50, "path": "apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift", "source": "Use only on a trusted private network.", "surface": "apple", @@ -25243,7 +25243,7 @@ }, { "kind": "ui-localized-call-multiline", - "line": 1443, + "line": 1470, "path": "apps/ios/Sources/Gateway/GatewayConnectionController.swift", "source": "Can't reach gateway at %1$@:%2$@. Verify Tailscale Serve is enabled and publishes this Gateway.", "surface": "apple", @@ -25251,7 +25251,7 @@ }, { "kind": "ui-localized-call", - "line": 1452, + "line": 1479, "path": "apps/ios/Sources/Gateway/GatewayConnectionController.swift", "source": "Can't reach gateway at %1$@:%2$@. Check Tailscale or LAN.", "surface": "apple", @@ -25259,7 +25259,7 @@ }, { "kind": "ui-localized-call-multiline", - "line": 1458, + "line": 1485, "path": "apps/ios/Sources/Gateway/GatewayConnectionController.swift", "source": "TLS fingerprint verification timed out for %1$@:%2$@. Secure endpoint was reached, but TLS did not finish in time.", "surface": "apple", @@ -25267,7 +25267,7 @@ }, { "kind": "ui-localized-call-multiline", - "line": 1466, + "line": 1493, "path": "apps/ios/Sources/Gateway/GatewayConnectionController.swift", "source": "No secure gateway endpoint was detected at %1$@:%2$@. Enable gateway TLS or Tailscale Serve, or use a trusted private LAN address with Unencrypted selected.", "surface": "apple", @@ -25275,7 +25275,7 @@ }, { "kind": "ui-localized-call", - "line": 1476, + "line": 1503, "path": "apps/ios/Sources/Gateway/GatewayConnectionController.swift", "source": "Could not read the TLS certificate from %1$@:%2$@.", "surface": "apple", @@ -25611,7 +25611,7 @@ }, { "kind": "conditional-branch", - "line": 634, + "line": 661, "path": "apps/ios/Sources/Gateway/GatewaySettingsStore.swift", "source": "\\(host):\\(port)", "surface": "apple", @@ -25619,7 +25619,7 @@ }, { "kind": "conditional-branch", - "line": 708, + "line": 736, "path": "apps/ios/Sources/Gateway/GatewaySettingsStore.swift", "source": "\\(legacy.host ?? \"\"):\\(legacy.port ?? 0)", "surface": "apple", @@ -26675,7 +26675,7 @@ }, { "kind": "conditional-branch", - "line": 105, + "line": 106, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Gateway auth token is missing.", "surface": "apple", @@ -26683,7 +26683,7 @@ }, { "kind": "conditional-branch", - "line": 109, + "line": 110, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Gateway rejected credentials.", "surface": "apple", @@ -26691,7 +26691,7 @@ }, { "kind": "conditional-branch", - "line": 113, + "line": 114, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Could not reach the gateway.", "surface": "apple", @@ -26699,7 +26699,7 @@ }, { "kind": "ui-modifier", - "line": 191, + "line": 192, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "QR Scanner Unavailable", "surface": "apple", @@ -26707,7 +26707,7 @@ }, { "kind": "ui-call", - "line": 197, + "line": 198, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "OK", "surface": "apple", @@ -26715,7 +26715,7 @@ }, { "kind": "ui-call", - "line": 302, + "line": 303, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Scan Setup Code", "surface": "apple", @@ -26723,7 +26723,7 @@ }, { "kind": "ui-call", - "line": 310, + "line": 311, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Cancel", "surface": "apple", @@ -26731,7 +26731,7 @@ }, { "kind": "ui-call", - "line": 317, + "line": 318, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Photos", "surface": "apple", @@ -26739,7 +26739,7 @@ }, { "kind": "ui-modifier", - "line": 358, + "line": 359, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Back", "surface": "apple", @@ -26747,7 +26747,7 @@ }, { "kind": "ui-call", - "line": 366, + "line": 367, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Close", "surface": "apple", @@ -26755,7 +26755,7 @@ }, { "kind": "ui-modifier", - "line": 392, + "line": 393, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Dismiss Keyboard", "surface": "apple", @@ -26763,7 +26763,7 @@ }, { "kind": "ui-call", - "line": 443, + "line": 444, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Mode", "surface": "apple", @@ -26771,7 +26771,7 @@ }, { "kind": "ui-call", - "line": 444, + "line": 445, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Discovery", "surface": "apple", @@ -26779,7 +26779,7 @@ }, { "kind": "ui-call", - "line": 446, + "line": 447, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Status", "surface": "apple", @@ -26787,7 +26787,7 @@ }, { "kind": "ui-call", - "line": 464, + "line": 465, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Choose a mode first.", "surface": "apple", @@ -26795,7 +26795,7 @@ }, { "kind": "ui-call", - "line": 469, + "line": 470, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Back to Mode Selection", "surface": "apple", @@ -26803,7 +26803,7 @@ }, { "kind": "ui-named-argument", - "line": 513, + "line": 514, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Manual Fallback", "surface": "apple", @@ -26811,7 +26811,7 @@ }, { "kind": "ui-named-argument", - "line": 517, + "line": 518, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Domain Settings", "surface": "apple", @@ -26819,7 +26819,7 @@ }, { "kind": "ui-call", - "line": 528, + "line": 529, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Developer Local", "surface": "apple", @@ -26827,7 +26827,7 @@ }, { "kind": "ui-call", - "line": 531, + "line": 532, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Default host is localhost. Use your Mac LAN IP if simulator networking requires it.", "surface": "apple", @@ -26835,7 +26835,7 @@ }, { "kind": "ui-call", - "line": 559, + "line": 560, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Gateway rejected credentials. Scan a fresh setup code or update token/password.", "surface": "apple", @@ -26843,7 +26843,7 @@ }, { "kind": "ui-call", - "line": 567, + "line": 568, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "OpenClaw is checking gateway and node access.", "surface": "apple", @@ -26851,7 +26851,7 @@ }, { "kind": "ui-call", - "line": 581, + "line": 582, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Resume After Approval", "surface": "apple", @@ -26859,7 +26859,7 @@ }, { "kind": "ui-call", - "line": 587, + "line": 588, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Pairing Approval", "surface": "apple", @@ -26867,7 +26867,7 @@ }, { "kind": "ui-localized-call", - "line": 593, + "line": 594, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Request ID: %@", "surface": "apple", @@ -26875,7 +26875,7 @@ }, { "kind": "ui-localized-call", - "line": 596, + "line": 597, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Request ID: check `openclaw devices list`.", "surface": "apple", @@ -26883,7 +26883,7 @@ }, { "kind": "ui-localized-call-multiline", - "line": 600, + "line": 601, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Approve this device on the gateway.\n1) `%1$@`\n2) `/pair approve` in your OpenClaw chat\n%2$@\nOpenClaw will also retry automatically when you return to this app.", "surface": "apple", @@ -26891,7 +26891,7 @@ }, { "kind": "ui-call", - "line": 617, + "line": 618, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Scan Setup Code Again", "surface": "apple", @@ -26899,7 +26899,7 @@ }, { "kind": "ui-call", - "line": 630, + "line": 631, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Retry Connection", "surface": "apple", @@ -26907,7 +26907,7 @@ }, { "kind": "ui-call", - "line": 661, + "line": 662, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Enter setup code", "surface": "apple", @@ -26915,7 +26915,7 @@ }, { "kind": "ui-call", - "line": 677, + "line": 678, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Apply", "surface": "apple", @@ -26923,7 +26923,7 @@ }, { "kind": "ui-call", - "line": 695, + "line": 696, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Setup Code", "surface": "apple", @@ -26931,7 +26931,7 @@ }, { "kind": "ui-call", - "line": 698, + "line": 699, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Use this if you have a setup code instead of scanning.", "surface": "apple", @@ -26939,7 +26939,7 @@ }, { "kind": "ui-call", - "line": 710, + "line": 711, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Host", "surface": "apple", @@ -26947,7 +26947,7 @@ }, { "kind": "ui-call", - "line": 711, + "line": 712, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Port", "surface": "apple", @@ -26955,7 +26955,7 @@ }, { "kind": "ui-call", - "line": 714, + "line": 715, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Discovery Domain (optional)", "surface": "apple", @@ -26963,7 +26963,7 @@ }, { "kind": "ui-call", - "line": 719, + "line": 720, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Gateway Auth Token", "surface": "apple", @@ -26971,7 +26971,7 @@ }, { "kind": "ui-call", - "line": 723, + "line": 724, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Gateway Password", "surface": "apple", @@ -26979,7 +26979,7 @@ }, { "kind": "ui-call", - "line": 753, + "line": 755, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Unencrypted", "surface": "apple", @@ -26987,7 +26987,7 @@ }, { "kind": "ui-call", - "line": 756, + "line": 758, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Secure (TLS)", "surface": "apple", @@ -26995,7 +26995,7 @@ }, { "kind": "ui-call", - "line": 760, + "line": 762, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Connection security", "surface": "apple", @@ -27003,7 +27003,7 @@ }, { "kind": "ui-call", - "line": 830, + "line": 832, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Connecting…", "surface": "apple", @@ -27011,7 +27011,7 @@ }, { "kind": "ui-call", - "line": 834, + "line": 836, "path": "apps/ios/Sources/Onboarding/OnboardingWizardView.swift", "source": "Connect", "surface": "apple", diff --git a/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt b/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt index 92f979226b7c..9207b89edaac 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt @@ -842,6 +842,7 @@ class MainViewModel private constructor( host = config.host, port = config.port, tlsEnabled = config.tls, + contextPath = config.contextPath, ) val targetAlreadyPaired = prefs.gatewayRegistry.entries.value @@ -876,6 +877,7 @@ class MainViewModel private constructor( host = config.host, port = config.port, tls = config.tls, + contextPath = config.contextPath, ), ) diff --git a/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt b/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt index d44f071bf84f..16c0cfb1ddc5 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt @@ -8530,6 +8530,7 @@ internal fun manualGatewayEndpoint(entry: GatewayRegistryEntry): GatewayEndpoint host = normalizedHost, port = normalizedPort, tlsEnabled = entry.tls, + contextPath = entry.contextPath, ) } @@ -8545,6 +8546,7 @@ internal fun gatewayRegistryEntry( host = endpoint.host, port = endpoint.port, tls = endpoint.tlsEnabled, + contextPath = endpoint.contextPath, lastConnectedAtMs = existing?.lastConnectedAtMs ?: 0L, ) } else { diff --git a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayEndpoint.kt b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayEndpoint.kt index fc11f3fc4834..55410ea4346d 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayEndpoint.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayEndpoint.kt @@ -12,6 +12,7 @@ data class GatewayEndpoint( val canvasPort: Int? = null, val tlsEnabled: Boolean = false, val tlsFingerprintSha256: String? = null, + val contextPath: String = "", ) { companion object { /** Builds a stable manual endpoint key that survives display-name changes. */ @@ -19,14 +20,65 @@ data class GatewayEndpoint( host: String, port: Int, tlsEnabled: Boolean = false, - ): GatewayEndpoint = - GatewayEndpoint( - stableId = "manual|${host.lowercase()}|$port", + contextPath: String = "", + ): GatewayEndpoint { + val normalizedContextPath = normalizeGatewayContextPath(contextPath) + val stableIdPath = if (normalizedContextPath.isEmpty()) "" else "|$normalizedContextPath" + return GatewayEndpoint( + stableId = "manual|${host.lowercase()}|$port$stableIdPath", name = "$host:$port", host = host, port = port, tlsEnabled = tlsEnabled, tlsFingerprintSha256 = null, + contextPath = normalizedContextPath, ) + } } } + +internal fun normalizeGatewayContextPath(value: String?): String { + val path = value.orEmpty() + if (path.isEmpty() || path == "/") return "" + val prefixed = if (path.startsWith('/')) path else "/$path" + val encoded = StringBuilder(prefixed.length) + var index = 0 + while (index < prefixed.length) { + if ( + prefixed[index] == '%' && + index + 2 < prefixed.length && + prefixed[index + 1].isAsciiHexDigit() && + prefixed[index + 2].isAsciiHexDigit() + ) { + encoded.append(prefixed, index, index + 3) + index += 3 + continue + } + val codePoint = prefixed.codePointAt(index) + if (isGatewayPathCodePoint(codePoint)) { + encoded.appendCodePoint(codePoint) + } else { + for (byte in String(Character.toChars(codePoint)).toByteArray(Charsets.UTF_8)) { + val value = byte.toInt() and 0xff + encoded.append('%') + encoded.append(HEX_DIGITS[value ushr 4]) + encoded.append(HEX_DIGITS[value and 0x0f]) + } + } + index += Character.charCount(codePoint) + } + return encoded.toString() +} + +private const val HEX_DIGITS = "0123456789ABCDEF" + +private fun Char.isAsciiHexDigit(): Boolean = this in '0'..'9' || this in 'A'..'F' || this in 'a'..'f' + +private fun isGatewayPathCodePoint(value: Int): Boolean = + value == '/'.code || + value == ':'.code || + value == '@'.code || + value in 'A'.code..'Z'.code || + value in 'a'.code..'z'.code || + value in '0'.code..'9'.code || + (value <= 0x7f && value.toChar() in "-._~!$&'()*+,;=") diff --git a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayRegistry.kt b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayRegistry.kt index da64d5104dce..a9d6af4f8041 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayRegistry.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayRegistry.kt @@ -28,6 +28,7 @@ data class GatewayRegistryEntry( val port: Int? = null, val tls: Boolean = true, val lastConnectedAtMs: Long = 0L, + val contextPath: String = "", ) @Serializable @@ -83,6 +84,7 @@ class GatewayRegistryStore( stableId = stableId, name = entry.name.trim().ifEmpty { stableId }, host = entry.host?.trim()?.takeIf { it.isNotEmpty() }, + contextPath = normalizeGatewayContextPath(entry.contextPath), lastConnectedAtMs = if (entry.lastConnectedAtMs == 0L) { existing?.lastConnectedAtMs ?: 0L diff --git a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt index fe3593b08734..9506f62e24d3 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewaySession.kt @@ -2175,9 +2175,11 @@ internal fun buildGatewayWebSocketUrl( host: String, port: Int, useTls: Boolean, + contextPath: String = "", ): String { val scheme = if (useTls) "wss" else "ws" - return "$scheme://${formatGatewayAuthority(host, port)}" + val path = normalizeGatewayContextPath(contextPath) + return "$scheme://${formatGatewayAuthority(host, port)}$path" } /** Builds one gateway upgrade request without exposing proxy credentials to cleartext routes. */ @@ -2186,7 +2188,15 @@ internal fun buildGatewayWebSocketUpgradeRequest( tls: GatewayTlsParams?, customHeadersProvider: ((stableId: String) -> Map)?, ): Request { - val request = Request.Builder().url(buildGatewayWebSocketUrl(endpoint.host, endpoint.port, tls != null)) + val request = + Request.Builder().url( + buildGatewayWebSocketUrl( + endpoint.host, + endpoint.port, + tls != null, + endpoint.contextPath, + ), + ) if (tls == null) return request.build() // Read at connect time so edits apply on the next reconnect. Headers may contain service tokens diff --git a/apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt b/apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt index 63f23454ba0b..667db7455310 100644 --- a/apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt +++ b/apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayConfigResolver.kt @@ -1,6 +1,7 @@ package ai.openclaw.app.ui import ai.openclaw.app.gateway.isLocalCleartextGatewayHost +import ai.openclaw.app.gateway.normalizeGatewayContextPath import ai.openclaw.app.i18n.NativeText import ai.openclaw.app.i18n.nativeString import ai.openclaw.app.i18n.nativeText @@ -20,6 +21,7 @@ internal data class GatewayEndpointConfig( val port: Int, val tls: Boolean, val displayUrl: String, + val contextPath: String = "", ) /** Effective transport shown by manual gateway forms before they connect. */ @@ -45,6 +47,7 @@ internal data class GatewayConnectConfig( val bootstrapToken: String, val token: String, val password: String, + val contextPath: String = "", ) /** How a connection attempt may update credentials already owned by the runtime. */ @@ -136,6 +139,7 @@ internal fun resolveGatewayConnectConfig( host = parsed.host, port = parsed.port, tls = parsed.tls, + contextPath = parsed.contextPath, bootstrapToken = setupBootstrapToken, token = sharedToken, password = sharedPassword, @@ -151,6 +155,7 @@ internal fun resolveGatewayConnectConfig( host = parsed.host, port = parsed.port, tls = parsed.tls, + contextPath = parsed.contextPath, bootstrapToken = bootstrapToken, token = token, password = password, @@ -206,7 +211,11 @@ internal fun resolveGatewayConnectPlan( return GatewayConnectPlan(config, action) } -private fun GatewayEndpointConfig.sameEndpoint(config: GatewayConnectConfig): Boolean = host.equals(config.host, ignoreCase = true) && port == config.port && tls == config.tls +private fun GatewayEndpointConfig.sameEndpoint(config: GatewayConnectConfig): Boolean = + host.equals(config.host, ignoreCase = true) && + port == config.port && + tls == config.tls && + contextPath == config.contextPath /** Parses an endpoint string and returns only the valid connection config. */ internal fun parseGatewayEndpoint(rawInput: String): GatewayEndpointConfig? = parseGatewayEndpointResult(rawInput).config @@ -221,6 +230,9 @@ internal fun parseGatewayEndpointResult(rawInput: String): GatewayEndpointParseR runCatching { URI(normalized) } .getOrNull() ?: return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INVALID_URL) + if (uri.rawUserInfo != null || uri.rawQuery != null || uri.rawFragment != null) { + return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INVALID_URL) + } val host = uri.host ?.trim() @@ -247,22 +259,31 @@ internal fun parseGatewayEndpointResult(rawInput: String): GatewayEndpointParseR val defaultPort = if (tls) 443 else 18789 val displayPort = if (tls) 443 else 80 val port = gatewayPort(uri.port, defaultPort) ?: return GatewayEndpointParseResult(error = GatewayEndpointValidationError.INVALID_URL) + val contextPath = normalizeGatewayContextPath(uri.rawPath) + val displayPath = contextPath val displayHost = if (host.contains(":")) "[$host]" else host val displayUrl = if (port == displayPort && defaultPort == displayPort) { - "${if (tls) "https" else "http"}://$displayHost" + "${if (tls) "https" else "http"}://$displayHost$displayPath" } else { - "${if (tls) "https" else "http"}://$displayHost:$port" + "${if (tls) "https" else "http"}://$displayHost:$port$displayPath" } return GatewayEndpointParseResult( - config = GatewayEndpointConfig(host = host, port = port, tls = tls, displayUrl = displayUrl), + config = + GatewayEndpointConfig( + host = host, + port = port, + tls = tls, + displayUrl = displayUrl, + contextPath = contextPath, + ), ) } /** Decodes base64url setup-code payloads produced by gateway onboarding. */ internal fun decodeGatewaySetupCode(rawInput: String): GatewaySetupCode? { - val trimmed = rawInput.trim() + val trimmed = stripPairingSetupUrlPrefix(rawInput.trim()) if (trimmed.isEmpty()) return null val padded = @@ -512,3 +533,12 @@ private fun jsonField( val value = (obj[key] as? JsonPrimitive)?.contentOrNull?.trim().orEmpty() return value.ifEmpty { null } } + +private const val PAIRING_SETUP_URL_PREFIX = "oc-pair://" + +private fun stripPairingSetupUrlPrefix(raw: String): String = + if (raw.startsWith(PAIRING_SETUP_URL_PREFIX, ignoreCase = true)) { + raw.substring(PAIRING_SETUP_URL_PREFIX.length) + } else { + raw + } diff --git a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayRegistryStoreTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayRegistryStoreTest.kt index 599298d927c3..59574e4d3d6c 100644 --- a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayRegistryStoreTest.kt +++ b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewayRegistryStoreTest.kt @@ -72,6 +72,38 @@ class GatewayRegistryStoreTest { assertEquals(first, second) } + @Test + fun roundTripPreservesManualGatewayContextPath() { + val (prefs, securePrefs) = freshPrefs() + val endpoint = + GatewayEndpoint.manual( + host = "gateway.example", + port = 443, + tlsEnabled = true, + contextPath = "/openclaw-gw", + ) + prefs.gatewayRegistry.upsert( + GatewayRegistryEntry( + stableId = endpoint.stableId, + kind = GatewayRegistryEntryKind.MANUAL, + name = endpoint.name, + host = endpoint.host, + port = endpoint.port, + tls = endpoint.tlsEnabled, + contextPath = endpoint.contextPath, + ), + ) + + val restored = GatewayRegistryStore(SecurePrefs(RuntimeEnvironment.getApplication(), securePrefs)) + + assertEquals( + "/openclaw-gw", + restored.entries.value + .single() + .contextPath, + ) + } + @Test fun failedRemovalCommitDoesNotPublishCandidateState() { val (_, securePrefs) = freshPrefs() diff --git a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTimeoutTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTimeoutTest.kt index 4bdcb23a3647..c265cf0ecaec 100644 --- a/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTimeoutTest.kt +++ b/apps/android/app/src/test/java/ai/openclaw/app/gateway/GatewaySessionInvokeTimeoutTest.kt @@ -21,6 +21,37 @@ class GatewaySessionInvokeTimeoutTest { assertEquals("wss://[::1]:443", buildGatewayWebSocketUrl("[::1]", 443, useTls = true)) } + @Test + fun buildGatewayWebSocketUrl_preservesAndEncodesContextPath() { + assertEquals( + "wss://gateway.example:443/openclaw%20gateway", + buildGatewayWebSocketUrl( + host = "gateway.example", + port = 443, + useTls = true, + contextPath = "/openclaw%20gateway", + ), + ) + assertEquals( + "wss://gateway.example:443/openclaw%2Fgateway", + buildGatewayWebSocketUrl( + host = "gateway.example", + port = 443, + useTls = true, + contextPath = "/openclaw%2Fgateway", + ), + ) + assertEquals( + "wss://gateway.example:443//openclaw", + buildGatewayWebSocketUrl( + host = "gateway.example", + port = 443, + useTls = true, + contextPath = "//openclaw", + ), + ) + } + @Test fun resolveInvokeResultAckTimeoutMs_usesFloorWhenMissingOrTooSmall() { assertEquals(15_000L, resolveInvokeResultAckTimeoutMs(null)) diff --git a/apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt b/apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt index 1ed9bc281427..795966366d3c 100644 --- a/apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt +++ b/apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt @@ -109,6 +109,30 @@ class GatewayConfigResolverTest { ) } + @Test + fun parseGatewayEndpointPreservesDecodedContextPath() { + val parsed = parseGatewayEndpoint("wss://gateway.example/openclaw%20gateway") + + assertEquals("/openclaw%20gateway", parsed?.contextPath) + assertEquals("https://gateway.example/openclaw%20gateway", parsed?.displayUrl) + } + + @Test + fun parseGatewayEndpointPreservesEscapedPathDelimiter() { + val parsed = parseGatewayEndpoint("wss://gateway.example/openclaw%2Fgateway") + + assertEquals("/openclaw%2Fgateway", parsed?.contextPath) + assertEquals("https://gateway.example/openclaw%2Fgateway", parsed?.displayUrl) + } + + @Test + fun parseGatewayEndpointPreservesRepeatedLeadingPathSlashes() { + val parsed = parseGatewayEndpoint("wss://gateway.example//openclaw") + + assertEquals("//openclaw", parsed?.contextPath) + assertEquals("https://gateway.example//openclaw", parsed?.displayUrl) + } + @Test fun parseGatewayEndpointRejectsNonLoopbackCleartextWsUrls() { assertEndpointRejected("ws://gateway.example") @@ -375,6 +399,22 @@ class GatewayConfigResolverTest { assertEquals(GatewayEndpointValidationError.INVALID_URL, parsed.error) } + @Test + fun parseGatewayEndpointResultRejectsCredentialsQueriesAndFragments() { + val urls = + listOf( + "wss://user@gateway.example/openclaw-gw", + "wss://gateway.example/openclaw-gw?mode=setup", + "wss://gateway.example/openclaw-gw#fragment", + ) + + for (url in urls) { + val parsed = parseGatewayEndpointResult(url) + assertNull(url, parsed.config) + assertEquals(url, GatewayEndpointValidationError.INVALID_URL, parsed.error) + } + } + @Test fun parseGatewayEndpointResultAllowsPrivateLanCleartextGateway() { val parsed = parseGatewayEndpointResult("ws://192.168.1.20:18789") @@ -420,6 +460,17 @@ class GatewayConfigResolverTest { assertNull(decoded?.password) } + @Test + fun decodeGatewaySetupCodeAcceptsPairingUrlWrapper() { + val setupCode = + encodeSetupCode("""{"url":"wss://gateway.example:18789","bootstrapToken":"Bootstrap-AbC123"}""") + + val decoded = decodeGatewaySetupCode("oc-pair://$setupCode") + + assertEquals("wss://gateway.example:18789", decoded?.url) + assertEquals("Bootstrap-AbC123", decoded?.bootstrapToken) + } + @Test fun manualTokenDetectsSetupCodePayloads() { val setupCode = @@ -450,6 +501,20 @@ class GatewayConfigResolverTest { assertEquals("", resolved?.password) } + @Test + fun resolveGatewayConnectConfigPreservesSetupContextPath() { + val resolved = + resolveConnectConfigFixture( + useSetupCode = true, + setupCode = setupCode("wss://gateway.example/openclaw-gw"), + ) + + assertEquals("gateway.example", resolved?.host) + assertEquals(443, resolved?.port) + assertEquals(true, resolved?.tls) + assertEquals("/openclaw-gw", resolved?.contextPath) + } + @Test fun resolveGatewayConnectConfigAcceptsQrJsonSetupCodePayload() { val setupCode = setupCode("wss://gateway.example:18789") @@ -630,9 +695,9 @@ class GatewayConfigResolverTest { val cases = listOf( "ws://gateway.local:18790" to true, - "http://192.168.1.20:18790/gateway?mode=manual" to true, + "http://192.168.1.20:18790/gateway" to true, "wss://gateway.example:8443" to false, - "https://gateway.example/gateway?mode=manual" to false, + "https://gateway.example/gateway" to false, "HTTPS://gateway.example:443" to false, "WS://GATEWAY.LOCAL.:18790" to true, "ws://[::1]:18790" to true, @@ -763,6 +828,9 @@ class GatewayConfigResolverTest { "gateway.local:18789#evil.example", "[::1]:18789?redirect=evil.example", "[::1]:18789#evil.example", + "wss://user@gateway.example/openclaw-gw", + "wss://gateway.example/openclaw-gw?mode=manual", + "wss://gateway.example/openclaw-gw#fragment", ) for (hostInput in hosts) { diff --git a/apps/ios/Sources/Design/SettingsProTab.swift b/apps/ios/Sources/Design/SettingsProTab.swift index 2c1ba0cdf379..4dcec1c6430f 100644 --- a/apps/ios/Sources/Design/SettingsProTab.swift +++ b/apps/ios/Sources/Design/SettingsProTab.swift @@ -56,6 +56,7 @@ struct SettingsProTab: View { @State var gatewayPassword = "" @State var gatewayCredentialFieldStableID: String? @State var manualGatewayPortText = "" + @State var manualGatewayContextPath: String? @State var setupStatusText: String? @State var setupAttemptID: UUID? @State var stagedGatewaySetupLink: GatewayConnectDeepLink? diff --git a/apps/ios/Sources/Design/SettingsProTabActions.swift b/apps/ios/Sources/Design/SettingsProTabActions.swift index 5731cccb7482..dc5105426bcf 100644 --- a/apps/ios/Sources/Design/SettingsProTabActions.swift +++ b/apps/ios/Sources/Design/SettingsProTabActions.swift @@ -214,6 +214,15 @@ extension SettingsProTab { func syncSettingsState() { self.refreshGatewayRegistry() self.manualGatewayPortText = self.manualGatewayPort > 0 ? String(self.manualGatewayPort) : "" + let activeManual = GatewaySettingsStore.activeGatewayEntry() + if activeManual?.kind == .manual, + activeManual?.host?.caseInsensitiveCompare(self.manualGatewayHost) == .orderedSame, + activeManual?.port == self.manualGatewayPort + { + self.manualGatewayContextPath = activeManual?.contextPath + } else { + self.manualGatewayContextPath = nil + } self.selectedAgentPickerId = self.appModel.selectedAgentId ?? "" self.defaultShareInstruction = ShareToAgentSettings.loadDefaultInstruction() self.refreshLocationPermissionSummary() @@ -371,6 +380,7 @@ extension SettingsProTab { self.manualGatewayPort = link.port self.manualGatewayPortText = String(link.port) self.manualGatewayTLS = link.tls + self.manualGatewayContextPath = link.contextPath let instanceId = GatewaySettingsStore.currentInstanceID() let setupAuth = GatewayConnectionController.ManualAuthOverride.setupAuth(from: link) self.gatewayCredentialFieldStableID = setupAuth.targetStableID @@ -543,6 +553,7 @@ extension SettingsProTab { host: host, port: port, useTLS: self.manualGatewayTLS, + contextPath: self.manualGatewayContextPath, authOverride: authOverride) // The controller now owns this attempt's immutable override. A later retry must reload // durable state so a spent bootstrap token cannot be resurrected from the live view. @@ -830,7 +841,8 @@ extension SettingsProTab { guard !host.isEmpty, let port = self.resolvedManualPort(host: host) else { return nil } return GatewayConnectionController.ManualAuthOverride.manualStableID( host: host, - port: port) + port: port, + contextPath: self.manualGatewayContextPath) } var gatewayCredentialTargetStableID: String? { @@ -879,6 +891,7 @@ extension SettingsProTab { get: { self.manualGatewayHost }, set: { value in let previousStableID = self.currentManualGatewayStableID + self.manualGatewayContextPath = nil self.manualGatewayHost = value if GatewayStableIdentifier.key(previousStableID) != GatewayStableIdentifier.key(self.currentManualGatewayStableID) @@ -968,6 +981,7 @@ extension SettingsProTab { get: { self.manualGatewayPortText }, set: { newValue in let previousStableID = self.currentManualGatewayStableID + self.manualGatewayContextPath = nil let filtered = newValue.filter(\.isNumber) self.manualGatewayPortText = filtered self.manualGatewayPort = Int(filtered) ?? 0 diff --git a/apps/ios/Sources/Design/SettingsProTabSections.swift b/apps/ios/Sources/Design/SettingsProTabSections.swift index 7231baa0c67d..7ec64ca7fa74 100644 --- a/apps/ios/Sources/Design/SettingsProTabSections.swift +++ b/apps/ios/Sources/Design/SettingsProTabSections.swift @@ -1334,6 +1334,7 @@ extension SettingsProTab { get: { self.manualGatewayTransport.effectiveTLS }, set: { enabled in guard !self.manualGatewayTransport.requiresTLS else { return } + self.manualGatewayContextPath = nil self.manualGatewayTLS = enabled }) } diff --git a/apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift b/apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift index 6731f5e86dfb..2302d6f0f803 100644 --- a/apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift +++ b/apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift @@ -16,13 +16,17 @@ struct GatewayManualTransportPresentation: Equatable { } extension GatewayConnectionController { - func buildGatewayURL(host: String, port: Int, useTLS: Bool) -> URL? { - let scheme = useTLS ? "wss" : "ws" - var components = URLComponents() - components.scheme = scheme - components.host = host - components.port = port - return components.url + func buildGatewayURL( + host: String, + port: Int, + useTLS: Bool, + contextPath: String? = nil) -> URL? + { + GatewayConnectEndpoint( + host: host, + port: port, + tls: useTLS, + contextPath: contextPath).websocketURL } func resolveManualUseTLS(host: String, useTLS: Bool) -> Bool { @@ -51,8 +55,8 @@ extension GatewayConnectionController { helperText: helperText) } - func manualStableID(host: String, port: Int) -> String { - ManualAuthOverride.manualStableID(host: host, port: port) + func manualStableID(host: String, port: Int, contextPath: String? = nil) -> String { + ManualAuthOverride.manualStableID(host: host, port: port, contextPath: contextPath) } func makeConnectOptions( diff --git a/apps/ios/Sources/Gateway/GatewayConnectionController+ManualAuth.swift b/apps/ios/Sources/Gateway/GatewayConnectionController+ManualAuth.swift index bfb54c339679..dae65f3c1225 100644 --- a/apps/ios/Sources/Gateway/GatewayConnectionController+ManualAuth.swift +++ b/apps/ios/Sources/Gateway/GatewayConnectionController+ManualAuth.swift @@ -189,8 +189,14 @@ extension GatewayConnectionController { suppressStoredDeviceAuth: pendingOverride.suppressStoredDeviceAuth) } - static func manualStableID(host: String, port: Int) -> String { - "manual|\(host.lowercased())|\(port)" + static func manualStableID(host: String, port: Int, contextPath: String? = nil) -> String { + let endpoint = GatewayConnectEndpoint( + host: host, + port: port, + tls: true, + contextPath: contextPath) + let pathSuffix = endpoint.contextPath.map { "|\($0)" } ?? "" + return "manual|\(host.lowercased())|\(port)\(pathSuffix)" } static func setupAuth(from link: GatewayConnectDeepLink) -> SetupAuth { @@ -198,7 +204,10 @@ extension GatewayConnectionController { token: link.token?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "", bootstrapToken: link.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "", password: link.password?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "", - targetStableID: self.manualStableID(host: link.host, port: link.port)) + targetStableID: self.manualStableID( + host: link.host, + port: link.port, + contextPath: link.contextPath)) } } } diff --git a/apps/ios/Sources/Gateway/GatewayConnectionController.swift b/apps/ios/Sources/Gateway/GatewayConnectionController.swift index 9631a1d0fc85..7fe34017799e 100644 --- a/apps/ios/Sources/Gateway/GatewayConnectionController.swift +++ b/apps/ios/Sources/Gateway/GatewayConnectionController.swift @@ -390,6 +390,7 @@ final class GatewayConnectionController { host: String, port: Int, useTLS: Bool, + contextPath: String? = nil, authOverride: ManualAuthOverride? = nil, forceReconnect: Bool = false) async { @@ -399,7 +400,10 @@ final class GatewayConnectionController { let resolvedUseTLS = self.resolveManualUseTLS(host: host, useTLS: useTLS) guard let resolvedPort = Self.resolvedManualPort(host: host, port: port) else { return } - let stableID = self.manualStableID(host: host, port: resolvedPort) + let stableID = self.manualStableID( + host: host, + port: resolvedPort, + contextPath: contextPath) self.pendingConnectionStableID = stableID await self.waitForPendingForgetCleanup(stableID: stableID) guard self.connectAttemptGeneration == connectAttempt.suppressionLease.generation else { return } @@ -422,7 +426,12 @@ final class GatewayConnectionController { : nil) let stored = GatewayTLSStore.loadFingerprint(stableID: stableID) if resolvedUseTLS, stored == nil { - guard let url = self.buildGatewayURL(host: host, port: resolvedPort, useTLS: true) else { return } + guard let url = self.buildGatewayURL( + host: host, + port: resolvedPort, + useTLS: true, + contextPath: contextPath) + else { return } self.appModel?.beginGatewayPreconnectVerification(statusText: "Verifying gateway TLS fingerprint…") guard let probeResult = await self.probeTLSFingerprint( host: host, @@ -465,7 +474,8 @@ final class GatewayConnectionController { guard let url = self.buildGatewayURL( host: host, port: resolvedPort, - useTLS: tlsParams?.required == true) + useTLS: tlsParams?.required == true, + contextPath: contextPath) else { return } let registryEntry = GatewaySettingsStore.GatewayRegistryEntry( stableID: stableID, @@ -474,6 +484,7 @@ final class GatewayConnectionController { host: host, port: resolvedPort, useTLS: resolvedUseTLS && tlsParams != nil, + contextPath: contextPath, lastConnectedAtMs: nil) guard self.persistActiveGateway(registryEntry) else { return } self.didAutoConnect = true @@ -496,7 +507,12 @@ final class GatewayConnectionController { switch active.kind { case .manual: guard let host = active.host, let port = active.port else { return } - await self.connectManual(host: host, port: port, useTLS: active.useTLS, forceReconnect: true) + await self.connectManual( + host: host, + port: port, + useTLS: active.useTLS, + contextPath: active.contextPath, + forceReconnect: true) case .discovered: if let gateway = self.gateways.first(where: { GatewayStableIdentifier.matches($0.stableID, active.stableID) @@ -506,7 +522,12 @@ final class GatewayConnectionController { } guard let fallback = self.mostRecentlyConnectedManualGateway() else { return } guard let host = fallback.host, let port = fallback.port else { return } - await self.connectManual(host: host, port: port, useTLS: fallback.useTLS, forceReconnect: true) + await self.connectManual( + host: host, + port: port, + useTLS: fallback.useTLS, + contextPath: fallback.contextPath, + forceReconnect: true) } } @@ -533,6 +554,7 @@ final class GatewayConnectionController { host: host, port: port, useTLS: entry.useTLS, + contextPath: entry.contextPath, forceReconnect: true) return nil case .discovered: @@ -815,6 +837,9 @@ final class GatewayConnectionController { host: pending.isManual ? prompt.host : nil, port: pending.isManual ? prompt.port : nil, useTLS: true, + contextPath: pending.isManual + ? URLComponents(url: pending.url, resolvingAgainstBaseURL: false)?.percentEncodedPath + : nil, lastConnectedAtMs: nil) guard self.persistActiveGateway(registryEntry) else { _ = GatewayTLSStore.clearFingerprint(stableID: pending.stableID) @@ -1056,7 +1081,8 @@ extension GatewayConnectionController { guard let url = self.buildGatewayURL( host: host, port: port, - useTLS: tlsParams?.required == true) + useTLS: tlsParams?.required == true, + contextPath: active.contextPath) else { return false } let credentials = GatewaySettingsStore.loadGatewayCredentials( @@ -1261,7 +1287,8 @@ extension GatewayConnectionController { let url = self.buildGatewayURL( host: host, port: port, - useTLS: tls?.required == true) + useTLS: tls?.required == true, + contextPath: entry.contextPath) else { return nil } route = (url, tls) case .discovered: diff --git a/apps/ios/Sources/Gateway/GatewaySettingsStore.swift b/apps/ios/Sources/Gateway/GatewaySettingsStore.swift index 88bb108fa330..0043d3391161 100644 --- a/apps/ios/Sources/Gateway/GatewaySettingsStore.swift +++ b/apps/ios/Sources/Gateway/GatewaySettingsStore.swift @@ -70,8 +70,29 @@ enum GatewaySettingsStore { var host: String? var port: Int? var useTLS: Bool + var contextPath: String? var lastConnectedAtMs: Int? + init( + stableID: String, + kind: Kind, + name: String, + host: String?, + port: Int?, + useTLS: Bool, + contextPath: String? = nil, + lastConnectedAtMs: Int?) + { + self.stableID = stableID + self.kind = kind + self.name = name + self.host = host + self.port = port + self.useTLS = useTLS + self.contextPath = contextPath + self.lastConnectedAtMs = lastConnectedAtMs + } + var id: GatewayStableIdentifier.Key { GatewayStableIdentifier.Key(self.stableID) } @@ -83,6 +104,7 @@ enum GatewaySettingsStore { lhs.host == rhs.host && lhs.port == rhs.port && lhs.useTLS == rhs.useTLS && + lhs.contextPath == rhs.contextPath && lhs.lastConnectedAtMs == rhs.lastConnectedAtMs } } @@ -628,6 +650,11 @@ enum GatewaySettingsStore { if entry.kind == .manual { let host = entry.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "" guard !host.isEmpty, let port = entry.port, (1...65535).contains(port) else { return nil } + let contextPath = GatewayConnectEndpoint( + host: host, + port: port, + tls: entry.useTLS, + contextPath: entry.contextPath).contextPath return GatewayRegistryEntry( stableID: stableID, kind: .manual, @@ -635,6 +662,7 @@ enum GatewaySettingsStore { host: host, port: port, useTLS: entry.useTLS, + contextPath: contextPath, lastConnectedAtMs: entry.lastConnectedAtMs) } return GatewayRegistryEntry( diff --git a/apps/ios/Sources/Onboarding/OnboardingWizardView.swift b/apps/ios/Sources/Onboarding/OnboardingWizardView.swift index 28feb30f3ba5..17125962fab2 100644 --- a/apps/ios/Sources/Onboarding/OnboardingWizardView.swift +++ b/apps/ios/Sources/Onboarding/OnboardingWizardView.swift @@ -27,6 +27,7 @@ struct OnboardingWizardView: View { @State private var manualPort: Int = 18789 @State private var manualPortText: String = "18789" @State private var manualTLS: Bool = true + @State private var manualContextPath: String? @State private var gatewayToken: String = "" @State private var gatewayPassword: String = "" @State private var gatewayCredentialFieldStableID: String? @@ -743,6 +744,7 @@ extension OnboardingWizardView { get: { self.manualTransport.effectiveTLS }, set: { enabled in guard !self.manualTransport.requiresTLS else { return } + self.manualContextPath = nil self.manualTLS = enabled }) } @@ -979,6 +981,7 @@ extension OnboardingWizardView { self.manualPort = link.port self.manualPortText = String(link.port) self.manualTLS = link.tls + self.manualContextPath = link.contextPath let setupAuth = GatewayConnectionController.ManualAuthOverride.setupAuth(from: link) self.gatewayCredentialFieldStableID = setupAuth.targetStableID if setupAuth.hasBootstrapToken { @@ -1221,6 +1224,7 @@ extension OnboardingWizardView { self.manualHost = host self.manualPort = port self.manualTLS = active.useTLS + self.manualContextPath = active.contextPath } else { self.manualHost = "openclaw.local" self.manualPort = 18789 @@ -1280,7 +1284,8 @@ extension OnboardingWizardView { guard !host.isEmpty, let port = self.resolvedManualPort(host: host) else { return nil } return GatewayConnectionController.ManualAuthOverride.manualStableID( host: host, - port: port) + port: port, + contextPath: self.manualContextPath) } private var gatewayCredentialTargetStableID: String? { @@ -1313,6 +1318,7 @@ extension OnboardingWizardView { get: { self.manualHost }, set: { value in let previousStableID = self.currentManualGatewayStableID + self.manualContextPath = nil self.manualHost = value if GatewayStableIdentifier.key(previousStableID) != GatewayStableIdentifier.key(self.currentManualGatewayStableID) @@ -1327,6 +1333,7 @@ extension OnboardingWizardView { get: { self.manualPortText }, set: { value in let previousStableID = self.currentManualGatewayStableID + self.manualContextPath = nil let digits = value.filter(\.isNumber) self.manualPortText = digits self.manualPort = min(Int(digits) ?? 0, 65535) @@ -1420,6 +1427,7 @@ extension OnboardingWizardView { private func applyModeDefaults(_ mode: OnboardingConnectionMode) { let previousStableID = self.currentManualGatewayStableID + self.manualContextPath = nil defer { if GatewayStableIdentifier.key(previousStableID) != GatewayStableIdentifier.key(self.currentManualGatewayStableID) @@ -1502,6 +1510,7 @@ extension OnboardingWizardView { host: host, port: port, useTLS: self.manualTLS, + contextPath: self.manualContextPath, authOverride: authOverride, forceReconnect: forceReconnect) // The controller now owns this attempt's immutable override. A later retry must reload diff --git a/apps/ios/Tests/GatewayConnectionControllerTests.swift b/apps/ios/Tests/GatewayConnectionControllerTests.swift index 30480f89638b..c5e25158fd4f 100644 --- a/apps/ios/Tests/GatewayConnectionControllerTests.swift +++ b/apps/ios/Tests/GatewayConnectionControllerTests.swift @@ -7,6 +7,10 @@ import UIKit @testable import OpenClaw @testable import OpenClawKit +private func percentEncodedPath(of url: URL?) -> String? { + url.flatMap { URLComponents(url: $0, resolvingAgainstBaseURL: false)?.percentEncodedPath } +} + @discardableResult private func saveActiveManualGateway( host: String, @@ -924,6 +928,46 @@ private func waitUntil( #expect(appModel.activeGatewayConnectConfig?.nodeOptions.deviceAuthGatewayID == setupAuth.targetStableID) } + @Test @MainActor func `setup context path survives registry reconnect`() async throws { + let registryIsolation = GatewayRegistryTestIsolation() + defer { registryIsolation.restore() } + let instanceID = "ios-context-path-\(UUID().uuidString)" + let temporaryState = try TemporaryOpenClawState(instanceID: instanceID) + defer { temporaryState.restore() } + let link = GatewayConnectDeepLink( + host: "192.168.1.41", + port: 18789, + tls: false, + contextPath: "/openclaw%2Fgateway", + bootstrapToken: nil, + token: nil, + password: nil) + let setupAuth = GatewayConnectionController.ManualAuthOverride.setupAuth(from: link) + let appModel = NodeAppModel() + defer { appModel.disconnectGateway() } + let controller = GatewayConnectionController(appModel: appModel, startDiscovery: false) + + await controller.connectManual( + host: link.host, + port: link.port, + useTLS: link.tls, + contextPath: link.contextPath, + authOverride: setupAuth.manualAuthOverride) + await waitUntil { appModel.activeGatewayConnectConfig != nil } + + #expect(percentEncodedPath(of: appModel.activeGatewayConnectConfig?.url) == "/openclaw%2Fgateway") + #expect(appModel.activeGatewayConnectConfig?.effectiveStableID == setupAuth.targetStableID) + let stored = try #require(GatewaySettingsStore.activeGatewayEntry()) + #expect(stored.contextPath == "/openclaw%2Fgateway") + + appModel.disconnectGateway() + await controller.connectActiveGateway() + await waitUntil { appModel.activeGatewayConnectConfig != nil } + + #expect(percentEncodedPath(of: appModel.activeGatewayConnectConfig?.url) == "/openclaw%2Fgateway") + #expect(appModel.activeGatewayConnectConfig?.effectiveStableID == stored.stableID) + } + @Test @MainActor func `legacy auth preserves proven relay credentials and otherwise requires full re-pair`() throws { let registryIsolation = GatewayRegistryTestIsolation() defer { registryIsolation.restore() } @@ -2178,6 +2222,35 @@ private func waitUntil( #expect(!GatewaySettingsStore.loadGatewayRegistry().entries.contains { $0.stableID == stableID }) } + @Test @MainActor func `manual trust handoff persists its context path`() async throws { + let registryIsolation = GatewayRegistryTestIsolation() + defer { registryIsolation.restore() } + let host = "context-path-trust.example.com" + let contextPath = "/openclaw-gateway" + let stableID = GatewayConnectionController.ManualAuthOverride.manualStableID( + host: host, + port: 443, + contextPath: contextPath) + defer { GatewayTLSStore.clearFingerprint(stableID: stableID) } + GatewayTLSStore.clearFingerprint(stableID: stableID) + let appModel = NodeAppModel() + defer { appModel.disconnectGateway() } + let controller = makeTLSProbeController(appModel: appModel, fingerprint: "context-path-fingerprint") + + await controller.connectManual( + host: host, + port: 443, + useTLS: true, + contextPath: contextPath) + #expect(controller.pendingTrustPrompt?.stableID == stableID) + await controller.acceptPendingTrustPrompt() + await waitUntil { appModel.activeGatewayConnectConfig != nil } + + #expect(percentEncodedPath(of: appModel.activeGatewayConnectConfig?.url) == contextPath) + let stored = try #require(GatewaySettingsStore.activeGatewayEntry()) + #expect(stored.contextPath == contextPath) + } + @Test @MainActor func `forget gateway preserves another gateway pending trust handoff`() async { let registryIsolation = GatewayRegistryTestIsolation() defer { registryIsolation.restore() } diff --git a/apps/ios/Tests/GatewaySettingsStoreTests.swift b/apps/ios/Tests/GatewaySettingsStoreTests.swift index 5f1ad6c49534..c72520d77607 100644 --- a/apps/ios/Tests/GatewaySettingsStoreTests.swift +++ b/apps/ios/Tests/GatewaySettingsStoreTests.swift @@ -695,6 +695,7 @@ private func withLastGatewaySnapshot(_ body: () -> Void) { host: "z.example.com", port: 443, useTLS: true, + contextPath: "/openclaw-gateway", lastConnectedAtMs: nil) let gatewayA = GatewaySettingsStore.GatewayRegistryEntry( stableID: "bonjour|alpha", @@ -716,6 +717,7 @@ private func withLastGatewaySnapshot(_ body: () -> Void) { #expect(registry.connectedStableIDs == [gatewayB.stableID]) #expect(GatewaySettingsStore.connectedGatewayEntries().map(\.stableID) == [gatewayB.stableID]) #expect(registry.entries.last?.lastConnectedAtMs == 1234) + #expect(registry.entries.last?.contextPath == "/openclaw-gateway") #expect(GatewaySettingsStore.upsertGatewayRegistryEntry(gatewayA)) #expect(KeychainStore.loadString(service: gatewayService, account: "gateway-registry") == firstJSON) diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift index 5cb0cb8c3185..2b7b25127029 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift @@ -4,6 +4,55 @@ private func defaultGatewayPort(tls: Bool) -> Int { tls ? 443 : 18789 } +private func normalizeGatewayContextPath(_ value: String?) -> String? { + guard let value, !value.isEmpty else { return nil } + let path = value.hasPrefix("/") ? value : "/\(value)" + guard path != "/" else { return nil } + // Keep valid escapes such as %2F and %FF intact because decoding them can + // change segment boundaries or reject valid non-UTF-8 path octets. + let allowed = CharacterSet.urlPathAllowed.subtracting(CharacterSet(charactersIn: "%?#")) + var encoded = "" + var index = path.startIndex + while index < path.endIndex { + if path[index] == "%" { + let first = path.index(after: index) + if first < path.endIndex { + let second = path.index(after: first) + if second < path.endIndex, + path[first].isHexDigit, + path[second].isHexDigit + { + let end = path.index(after: second) + encoded.append(contentsOf: path[index.. GatewayConnectDeepLink { @@ -96,6 +148,7 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { host: endpoint.host, port: endpoint.port, tls: endpoint.tls, + contextPath: endpoint.contextPath, bootstrapToken: self.bootstrapToken, token: self.token, password: self.password) @@ -144,8 +197,14 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { /// and `tls`. In both cases, the optional `bootstrapToken`, `token`, and `password` fields /// are also supported. public static func fromSetupCode(_ code: String) -> GatewayConnectDeepLink? { - let trimmed = code.trimmingCharacters(in: .whitespacesAndNewlines) + var trimmed = code.trimmingCharacters(in: .whitespacesAndNewlines) guard !trimmed.isEmpty else { return nil } + if trimmed.range( + of: self.pairingSetupURLPrefix, + options: [.anchored, .caseInsensitive]) != nil + { + trimmed = String(trimmed.dropFirst(self.pairingSetupURLPrefix.count)) + } if let link = decodeSetupPayload(from: Data(trimmed.utf8)) { return link } @@ -185,12 +244,17 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { } if let primary = links.first { let fallbacks = links.dropFirst().map { - GatewayConnectEndpoint(host: $0.host, port: $0.port, tls: $0.tls) + GatewayConnectEndpoint( + host: $0.host, + port: $0.port, + tls: $0.tls, + contextPath: $0.contextPath) } return GatewayConnectDeepLink( host: primary.host, port: primary.port, tls: primary.tls, + contextPath: primary.contextPath, bootstrapToken: primary.bootstrapToken, token: primary.token, password: primary.password, @@ -221,7 +285,11 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { password: String?) -> GatewayConnectDeepLink? { guard let parsed = URLComponents(string: urlString), - let hostname = parsed.host, !hostname.isEmpty + let hostname = parsed.host, !hostname.isEmpty, + parsed.user == nil, + parsed.password == nil, + parsed.query == nil, + parsed.fragment == nil else { return nil } let scheme = (parsed.scheme ?? "ws").lowercased() @@ -236,6 +304,7 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { host: hostname, port: parsed.port ?? defaultGatewayPort(tls: tls), tls: tls, + contextPath: parsed.percentEncodedPath, bootstrapToken: bootstrapToken, token: token, password: password) @@ -245,6 +314,7 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { host: String, port: Int, tls: Bool, + contextPath: String? = nil, bootstrapToken: String?, token: String?, password: String?) -> GatewayConnectDeepLink? @@ -253,6 +323,7 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { host: host, port: port, tls: tls, + contextPath: contextPath, bootstrapToken: bootstrapToken, token: token, password: password) @@ -285,14 +356,42 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable { } public struct GatewayConnectEndpoint: Codable, Sendable, Equatable { + private enum CodingKeys: String, CodingKey { + case host + case port + case tls + case contextPath + } + public let host: String public let port: Int public let tls: Bool + public let contextPath: String? - public init(host: String, port: Int, tls: Bool) { + public init(host: String, port: Int, tls: Bool, contextPath: String? = nil) { self.host = host self.port = port self.tls = tls + self.contextPath = normalizeGatewayContextPath(contextPath) + } + + public init(from decoder: Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + self.host = try container.decode(String.self, forKey: .host) + self.port = try container.decode(Int.self, forKey: .port) + self.tls = try container.decode(Bool.self, forKey: .tls) + self.contextPath = try normalizeGatewayContextPath( + container.decodeIfPresent(String.self, forKey: .contextPath)) + } + + public var websocketURL: URL? { + guard (1...65535).contains(self.port) else { return nil } + var components = URLComponents() + components.scheme = self.tls ? "wss" : "ws" + components.host = self.host + components.port = self.port + components.percentEncodedPath = self.contextPath ?? "" + return components.url } } diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift index ef5b91843760..68cb49478c88 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift @@ -17890,6 +17890,7 @@ public struct DevicePairSetupCodeResult: Codable, Sendable { public let urlsource: String public let access: AnyCodable? public let accessdowngraded: Bool? + public let expiresatms: Int? public init( setupcode: String, @@ -17899,7 +17900,8 @@ public struct DevicePairSetupCodeResult: Codable, Sendable { auth: AnyCodable, urlsource: String, access: AnyCodable? = nil, - accessdowngraded: Bool? = nil) + accessdowngraded: Bool? = nil, + expiresatms: Int? = nil) { self.setupcode = setupcode self.qrdataurl = qrdataurl @@ -17909,6 +17911,7 @@ public struct DevicePairSetupCodeResult: Codable, Sendable { self.urlsource = urlsource self.access = access self.accessdowngraded = accessdowngraded + self.expiresatms = expiresatms } private enum CodingKeys: String, CodingKey { @@ -17920,6 +17923,7 @@ public struct DevicePairSetupCodeResult: Codable, Sendable { case urlsource = "urlSource" case access case accessdowngraded = "accessDowngraded" + case expiresatms = "expiresAtMs" } } diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeepLinksSecurityTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeepLinksSecurityTests.swift index 9581aa62851a..ab510a825240 100644 --- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeepLinksSecurityTests.swift +++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeepLinksSecurityTests.swift @@ -106,6 +106,47 @@ private func gatewayLink(from raw: String) -> GatewayConnectDeepLink? { password: nil)) } + @Test func setupCodeAcceptsPairingURLWrapperWithoutLowercasingPayload() { + let payload = #"{"url":"wss://gateway.example:8443","bootstrapToken":"Bootstrap-AbC123"}"# + let code = setupCode(from: payload) + + #expect( + GatewayConnectDeepLink.fromSetupCode("oc-pair://\(code)") == + GatewayConnectDeepLink.fromSetupCode(code)) + } + + @Test func setupCodePreservesPrimaryGatewayContextPath() { + let payload = #"{"url":"wss://gateway.example/openclaw-gw","bootstrapToken":"tok"}"# + let link = GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) + + #expect(link?.contextPath == "/openclaw-gw") + #expect(link?.websocketURL?.absoluteString == "wss://gateway.example:443/openclaw-gw") + } + + @Test func setupCodeDecodesGatewayContextPathExactlyOnce() { + let payload = #"{"url":"wss://gateway.example/openclaw%20gateway","bootstrapToken":"tok"}"# + let link = GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) + + #expect(link?.contextPath == "/openclaw%20gateway") + #expect(link?.websocketURL?.absoluteString == "wss://gateway.example:443/openclaw%20gateway") + } + + @Test func setupCodePreservesEscapedGatewayPathDelimiter() { + let payload = #"{"url":"wss://gateway.example/openclaw%2Fgateway","bootstrapToken":"tok"}"# + let link = GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) + + #expect(link?.contextPath == "/openclaw%2Fgateway") + #expect(link?.websocketURL?.absoluteString == "wss://gateway.example:443/openclaw%2Fgateway") + } + + @Test func setupCodePreservesNonUTF8GatewayPathOctet() { + let payload = #"{"url":"wss://gateway.example/openclaw%FFgateway","bootstrapToken":"tok"}"# + let link = GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) + + #expect(link?.contextPath == "/openclaw%FFgateway") + #expect(link?.websocketURL?.absoluteString == "wss://gateway.example:443/openclaw%FFgateway") + } + @Test func setupCodeAllowsPrivateLanWs() { let payload = #"{"url":"ws://192.168.1.20:18789","bootstrapToken":"tok"}"# #expect( @@ -131,17 +172,18 @@ private func gatewayLink(from raw: String) -> GatewayConnectDeepLink? { } @Test func setupCodeParsesOrderedGatewayFallbacks() throws { - let payload = #"{"url":"ws://192.168.1.20:18789","urls":["ws://192.168.1.20:18789","wss://gateway.tailnet.ts.net:8443"],"bootstrapToken":"tok"}"# + let payload = #"{"url":"ws://192.168.1.20:18789/lan-gw","urls":["ws://192.168.1.20:18789/lan-gw","wss://gateway.tailnet.ts.net:8443/tailnet-gw"],"bootstrapToken":"tok"}"# let link = GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) #expect(link?.connectionEndpoints == [ - .init(host: "192.168.1.20", port: 18789, tls: false), - .init(host: "gateway.tailnet.ts.net", port: 8443, tls: true), + .init(host: "192.168.1.20", port: 18789, tls: false, contextPath: "/lan-gw"), + .init(host: "gateway.tailnet.ts.net", port: 8443, tls: true, contextPath: "/tailnet-gw"), ]) #expect(try link?.selectingEndpoint(#require(link?.connectionEndpoints[1])) == .init( host: "gateway.tailnet.ts.net", port: 8443, tls: true, + contextPath: "/tailnet-gw", bootstrapToken: "tok", token: nil, password: nil)) @@ -154,9 +196,35 @@ private func gatewayLink(from raw: String) -> GatewayConnectDeepLink? { GatewayConnectDeepLink.self, from: Data(payload.utf8)) + #expect(link.contextPath == nil) #expect(link.fallbackEndpoints.isEmpty) } + @Test func legacyEncodedFallbackEndpointDecodesWithoutContextPath() throws { + let payload = #"{"host":"gateway.example","port":443,"tls":true,"fallbackEndpoints":[{"host":"fallback.example","port":443,"tls":true}]}"# + + let link = try JSONDecoder().decode( + GatewayConnectDeepLink.self, + from: Data(payload.utf8)) + + #expect(link.fallbackEndpoints == [ + .init(host: "fallback.example", port: 443, tls: true), + ]) + } + + @Test func setupCodeRejectsGatewayURLMetadata() { + let urls = [ + "wss://user@gateway.example/openclaw-gw", + "wss://gateway.example/openclaw-gw?mode=setup", + "wss://gateway.example/openclaw-gw#fragment", + ] + + for url in urls { + let payload = #"{"url":"\#(url)","bootstrapToken":"tok"}"# + #expect(GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == nil) + } + } + @Test func setupCodeDropsInsecureGatewayFallbacks() { let payload = #"{"url":"ws://attacker.example:18789","urls":["ws://attacker.example:18789","wss://gateway.tailnet.ts.net"],"bootstrapToken":"tok"}"# diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json index b14cb45a6a19..8787aca39090 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness-runtime.json @@ -1 +1 @@ -{"contentHash":"40f4454b9a60030b2a1ba050abaad8993e821cb84444365728dc3d12de86e1af","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} +{"contentHash":"71bba45fd19e23bdcad65dc617c22dbdfc7b3c2957b7aec28fd470f4d98de9e1","entrypoint":"agent-harness-runtime","importSpecifier":"openclaw/plugin-sdk/agent-harness-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json index 6c5a518d1f2b..9c6df077a3de 100644 --- a/docs/.generated/plugin-sdk-api-baseline/agent-harness.json +++ b/docs/.generated/plugin-sdk-api-baseline/agent-harness.json @@ -1 +1 @@ -{"contentHash":"c700bd1f9821574a3d0a20815d55fc8b3857d71cdbfeab0a9bfb394bb81fe745","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} +{"contentHash":"e0f0d842ad89e78e3f40e545821fc39a3fccbdb43f592f8d298dae35b197f792","entrypoint":"agent-harness","importSpecifier":"openclaw/plugin-sdk/agent-harness"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-core.json b/docs/.generated/plugin-sdk-api-baseline/channel-core.json index 886771e7b69f..85adde0f6709 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-core.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-core.json @@ -1 +1 @@ -{"contentHash":"30538b51154ba0bdebf6bf02eefd16c73b7fd1043b074f3595db3a3088bfc98c","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} +{"contentHash":"970f98d008137e204aed058afc38196a2f4862ccfcaf0b1aeb35fc565060e80d","entrypoint":"channel-core","importSpecifier":"openclaw/plugin-sdk/channel-core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json index 291a40c23610..ed881e464452 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-entry-contract.json @@ -1 +1 @@ -{"contentHash":"0c9c99f96d0c050db645580b2bb91405485423e2d7fd14031b101d4b44026537","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} +{"contentHash":"a1f13d0608db5e34ac8a96d65522063ad164f04779905aa95263c6a95ddd8477","entrypoint":"channel-entry-contract","importSpecifier":"openclaw/plugin-sdk/channel-entry-contract"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-message.json b/docs/.generated/plugin-sdk-api-baseline/channel-message.json index 571e4e56af2b..e85c0df2e016 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-message.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-message.json @@ -1 +1 @@ -{"contentHash":"ad9dc515e2c9ed1c15397a9846c6212c56276c5dda24635be3f315312f077e43","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} +{"contentHash":"f8c7d30e1606d19045fa79d6fad7713cdad0c0da719586fd083630c97caa7a48","entrypoint":"channel-message","importSpecifier":"openclaw/plugin-sdk/channel-message"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json index 6e63230bb6da..b2d74ee3c160 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-outbound.json @@ -1 +1 @@ -{"contentHash":"29089a2b47826afc64a85979f3606d4140aa272a77e90247dd92e65bca3a2dd8","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} +{"contentHash":"7b9539b83b719a681f4ad601650bd4eda9d313e2cbc1d8f2caa18429e3204f6e","entrypoint":"channel-outbound","importSpecifier":"openclaw/plugin-sdk/channel-outbound"} diff --git a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json index 3c1e1c698bd6..162e94bb99e6 100644 --- a/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json +++ b/docs/.generated/plugin-sdk-api-baseline/channel-plugin-common.json @@ -1 +1 @@ -{"contentHash":"1eda9bc8cdf2adff5b1c04f0d9eaafed8c448bccae1728ad7a6475040e48c960","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} +{"contentHash":"0912d9c29be111d7899d426420841f63efd4b59f2c905d0b0f676522987a7435","entrypoint":"channel-plugin-common","importSpecifier":"openclaw/plugin-sdk/channel-plugin-common"} diff --git a/docs/.generated/plugin-sdk-api-baseline/core.json b/docs/.generated/plugin-sdk-api-baseline/core.json index f2423c7ed98a..e1c08b7db17e 100644 --- a/docs/.generated/plugin-sdk-api-baseline/core.json +++ b/docs/.generated/plugin-sdk-api-baseline/core.json @@ -1 +1 @@ -{"contentHash":"ca227941dce03110d71765ad1d2e8df89e30d09c19f664082d4e2a113937211b","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} +{"contentHash":"dab3cc4ad5d01284c3458191168aad2eb829731334b5c2bc58909eed9df05a7f","entrypoint":"core","importSpecifier":"openclaw/plugin-sdk/core"} diff --git a/docs/.generated/plugin-sdk-api-baseline/discord.json b/docs/.generated/plugin-sdk-api-baseline/discord.json index e984996cdaba..a2919073cd3e 100644 --- a/docs/.generated/plugin-sdk-api-baseline/discord.json +++ b/docs/.generated/plugin-sdk-api-baseline/discord.json @@ -1 +1 @@ -{"contentHash":"6de4593681bd8424e7334550612c4e1e9962e1a4dda50effc6890da7a4076fe5","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} +{"contentHash":"1aee60635c4552486cdd7a14e9767d39aef9ba90e38db8064a4bfa8d68ab8df3","entrypoint":"discord","importSpecifier":"openclaw/plugin-sdk/discord"} diff --git a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json index 8879d0effadc..a569656e1a2d 100644 --- a/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/gateway-runtime.json @@ -1 +1 @@ -{"contentHash":"225e30b4d18d4c77aee34623d9e69263835eddf690d0ad6d9dc1285e8f349d06","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} +{"contentHash":"9e84fb5aa07d64518232ebf5d169f0a05d82789b1d4b3c2ade005a3c055921ad","entrypoint":"gateway-runtime","importSpecifier":"openclaw/plugin-sdk/gateway-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json index c64cc8330183..afcc37c21b19 100644 --- a/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json +++ b/docs/.generated/plugin-sdk-api-baseline/inbound-reply-dispatch.json @@ -1 +1 @@ -{"contentHash":"b156cd10587667ccf02b0fd7e066de0cf37cd219f0c07c8fb065c293e1f675de","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} +{"contentHash":"12fcbb778c804d28f2cb15077026e97edc13250b55b8fe7934d4e50d1c184fe1","entrypoint":"inbound-reply-dispatch","importSpecifier":"openclaw/plugin-sdk/inbound-reply-dispatch"} diff --git a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json index 65f9fa9c219a..0699a9357986 100644 --- a/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/meeting-runtime.json @@ -1 +1 @@ -{"contentHash":"1e566fe360e6b82b1d31ded008160ddbfbc97713d3d55f1b9f3ba641825d537c","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} +{"contentHash":"805c19a024cee0370a81b3b8d60a88276b7f2ccfc3288e3082184e6d0503b4cc","entrypoint":"meeting-runtime","importSpecifier":"openclaw/plugin-sdk/meeting-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json index 0ae521065c36..65921fc6d0bf 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-entry.json @@ -1 +1 @@ -{"contentHash":"05d6916c82b9a5b512fd541e68a56040aee9a8a23019e6c70e8a62cdcee16716","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} +{"contentHash":"90de46f1e0f51185b27f551eb1a90a5cba679927da65b45bccdd2adb88b7cff6","entrypoint":"plugin-entry","importSpecifier":"openclaw/plugin-sdk/plugin-entry"} diff --git a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json index 791f17163d87..edb314b2ad91 100644 --- a/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/plugin-runtime.json @@ -1 +1 @@ -{"contentHash":"0d68fc98d2c75f2dc4d74670b8d902000c7af2945b65aeae2f783a8e705675a7","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} +{"contentHash":"169d46618a3fe5095c199ed12ef6bba91f64ec0cac95003dba9b61639c1b4c06","entrypoint":"plugin-runtime","importSpecifier":"openclaw/plugin-sdk/plugin-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json index 75abdbb72639..1b686c756917 100644 --- a/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json +++ b/docs/.generated/plugin-sdk-api-baseline/provider-catalog-runtime.json @@ -1 +1 @@ -{"contentHash":"34eb7210106298e9efc89a2891438dd05e198a1b6a7510f0c948c4f916b752ca","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} +{"contentHash":"ffa80d2beeb2d3b6e3aff7520da7fa500b2b91d4466b636ea546096472d15e44","entrypoint":"provider-catalog-runtime","importSpecifier":"openclaw/plugin-sdk/provider-catalog-runtime"} diff --git a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json index 29e0e38c38df..837a9e8119aa 100644 --- a/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json +++ b/docs/.generated/plugin-sdk-api-baseline/tool-plugin.json @@ -1 +1 @@ -{"contentHash":"e573cfb3d9ee7c9f79aee3f425fd804953e9df34283196006033dea6ee302396","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} +{"contentHash":"14e690663ce3426b199897c3e08bc8fcde45e3ef34d52acf8ae55d5e837eb738","entrypoint":"tool-plugin","importSpecifier":"openclaw/plugin-sdk/tool-plugin"} diff --git a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json index e154f726fa75..58d0eaf5e3ab 100644 --- a/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json +++ b/docs/.generated/plugin-sdk-api-baseline/webhook-ingress.json @@ -1 +1 @@ -{"contentHash":"baecdbe479ff6b3a7ae95d67ce3539d61acd424cea71692a04276972884ea372","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} +{"contentHash":"886fac651c8ee8a85ea50cc883c475a966b66d91e7e65f01b08c995c20e8add7","entrypoint":"webhook-ingress","importSpecifier":"openclaw/plugin-sdk/webhook-ingress"} diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md index c82c31d81ca9..9fe6bccb5fcd 100644 --- a/docs/channels/pairing.md +++ b/docs/channels/pairing.md @@ -139,7 +139,7 @@ creates a device pairing request that must be approved. Use an already connected Control UI session with `operator.admin` access: 1. Open the Control UI and go to **Settings → Devices**. -2. On the **Devices** page, click **Pair mobile device**. +2. On the **Devices** page, click **Pair device**. 3. Keep **Full access (recommended)**, or select **Limited access** to omit administrative Gateway controls. 4. Click **Create setup code**. diff --git a/docs/cli/node.md b/docs/cli/node.md index c81e3ae4e343..e4b4980be671 100644 --- a/docs/cli/node.md +++ b/docs/cli/node.md @@ -74,9 +74,18 @@ Disable it on the node if needed: openclaw node run --host --port 18789 ``` +Or paste a short-lived node setup link from the Control UI Devices page: + +```bash +openclaw node run --pair "oc-pair://" +``` + Options: - `--host `: Gateway WebSocket host (default: `127.0.0.1`) +- `--pair `: Read the Gateway endpoint, bootstrap token, TLS mode, + and optional certificate pin from a setup code or `oc-pair://` URL. Explicit + gateway flags override values from `--pair`. - `--port `: Gateway WebSocket port (default: `18789`) - `--context-path `: Gateway WebSocket context path (e.g. `/openclaw-gw`). Appended to the WebSocket URL. - `--tls`: Use TLS for the gateway connection @@ -87,6 +96,12 @@ Options: ## Gateway auth for node host +`--pair` uses a 10-minute single-use bootstrap token for the first connection. +After pairing, reconnects use the durable device credential. The setup link +does not pre-approve `system.run`; normal node approval and SSH verification +remain in force. `node install --pair` is intentionally unavailable because a +short-lived bearer setup link must not be persisted in service arguments. + `openclaw node run` and `openclaw node install` resolve gateway auth from config/env (no `--token`/`--password` flags on node commands): - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` are checked first. diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md index e2dc55e2d2f8..871f5c9034df 100644 --- a/docs/gateway/pairing.md +++ b/docs/gateway/pairing.md @@ -38,6 +38,28 @@ Pending requests expire automatically **5 minutes after the node's last retry** — an actively reconnecting node keeps its one pending request alive rather than generating a fresh request (and approval prompt) per attempt. +## One-paste node pairing + +In the Control UI Devices page, open the pairing dialog, choose **Node host**, +and copy the generated command to the device: + +```bash +openclaw node run --pair "oc-pair://" +``` + +The setup link carries the Gateway endpoint, a short-lived single-use bootstrap +token, and a TLS certificate pin when the Gateway directly serves a pinnable +leaf certificate. The bootstrap token expires after 10 minutes. Explicit +`--host`, `--port`, `--context-path`, `--tls`/`--no-tls`, and +`--tls-fingerprint` flags override values from `--pair`. + +The bootstrap token and resulting device credential are separate, like a +short-lived Tailscale auth key and the durable device identity it admits. +Revoking or expiring the setup link does not revoke the paired device; remove +the device separately when needed. The link never pre-approves `system.run` or +folder sync. Those operations still use pending approval or +[SSH-verified device auto-approval](#ssh-verified-device-auto-approval-default). + ## CLI workflow (headless friendly) ```bash diff --git a/docs/nodes/index.md b/docs/nodes/index.md index 1e36f38c1bbd..cfc879195d0b 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -94,7 +94,21 @@ On the node machine: openclaw node run --host --port 18789 --display-name "Build Node" ``` -`node run` also accepts `--context-path` (Gateway WS context path), `--tls`, `--tls-fingerprint `, and `--node-id` (override the legacy client instance ID; this does not reset pairing). On macOS, pass `--share-installed-apps` to advertise `device.apps`; sharing is off by default. Use `--no-share-installed-apps` to disable a previously saved opt-in. +For one-paste setup, create a **Node host** setup link from the Control UI +Devices page, then run its copyable command on the node machine: + +```bash +openclaw node run --pair "oc-pair://" +``` + +The link is single-use and expires after 10 minutes. It supplies the endpoint, +bootstrap token, TLS mode, and certificate pin when available. Explicit +gateway flags override the corresponding `--pair` values. Pairing does not +pre-approve command execution; the first `system.run` request still follows +the normal pending-approval or SSH-verification path. See +[Node pairing](/gateway/pairing#one-paste-node-pairing). + +`node run` also accepts `--pair`, `--context-path` (Gateway WS context path), `--tls`, `--tls-fingerprint `, and `--node-id` (override the legacy client instance ID; this does not reset pairing). On macOS, pass `--share-installed-apps` to advertise `device.apps`; sharing is off by default. Use `--no-share-installed-apps` to disable a previously saved opt-in. ### Remote gateway via SSH tunnel (loopback bind) diff --git a/docs/platforms/ios.md b/docs/platforms/ios.md index c01329a72822..bc70546cfd7c 100644 --- a/docs/platforms/ios.md +++ b/docs/platforms/ios.md @@ -53,7 +53,7 @@ Gateway has not been configured yet, run `openclaw onboard` first so setup-code creation has a token or password auth path. 2. Open the [Control UI](/web/control-ui), select **Nodes**, and click - **Pair mobile device** on the **Devices** page. Full access is recommended + **Pair device** on the **Devices** page. Full access is recommended and selected by default; choose Limited access only when you want to omit administrative Gateway controls, then click **Create setup code**. diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index b7782a3e3eb6..6b10ae25cb2b 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -98,7 +98,7 @@ An already paired administrator can create the iOS/Android connection QR without - Select **Devices**, then click **Pair mobile device** in the **Devices** card. + Select **Devices**, then click **Pair device** in the **Devices** card. In the OpenClaw mobile app, open **Settings** → **Gateway** and scan the QR code. You can copy and paste the setup code instead. diff --git a/packages/gateway-client/src/browser-device-auth.test.ts b/packages/gateway-client/src/browser-device-auth.test.ts index e19ed8dd46e5..0570dcccd9c3 100644 --- a/packages/gateway-client/src/browser-device-auth.test.ts +++ b/packages/gateway-client/src/browser-device-auth.test.ts @@ -119,21 +119,24 @@ describe("GatewayBrowserDeviceAuthLifecycle", () => { expect(plan.device?.signedAt).toBe(123); }); - it("never persists bootstrap or shared-secret credentials", async () => { + it("uses only the preferred bootstrap credential and never persists it", async () => { + const sign = vi.fn(async () => "signature"); const store = vi.fn(); const lifecycle = new GatewayBrowserDeviceAuthLifecycle({ loadIdentity: async () => ({ deviceId: "device", publicKey: "public", - sign: async () => "signature", + sign, }), tokenStore: { load: () => null, store, clear: vi.fn() }, + nowMs: () => 123, }); const plan = await lifecycle.buildPlan({ client, role: "operator", defaultScopes: ["operator.read"], bootstrapScopes: ["operator.read", "operator.write"], + token: "test-shared-token", bootstrapToken: "test-bootstrap-token", password: "test-password", preferBootstrapToken: true, @@ -141,7 +144,12 @@ describe("GatewayBrowserDeviceAuthLifecycle", () => { }); expect(plan.auth?.bootstrapToken).toBe("test-bootstrap-token"); - expect(plan.auth?.password).toBe("test-password"); + expect(plan.auth?.token).toBeUndefined(); + expect(plan.auth?.password).toBeUndefined(); + expect(plan.selectedAuth.signatureToken).toBe("test-bootstrap-token"); + expect(sign).toHaveBeenCalledWith( + "v3|device|openclaw-browser-copilot|ui|operator|operator.read,operator.write|123|test-bootstrap-token|nonce|chrome|extension", + ); await lifecycle.acceptHello({ auth: { role: "operator", scopes: [] } }, plan); expect(store).not.toHaveBeenCalled(); }); diff --git a/packages/gateway-client/src/client.ts b/packages/gateway-client/src/client.ts index 677e3b0b46b3..cd8a8a368b06 100644 --- a/packages/gateway-client/src/client.ts +++ b/packages/gateway-client/src/client.ts @@ -285,6 +285,7 @@ export type GatewayClientCloseInfo = { phase: "pre-hello" | "post-hello"; socketOpened: boolean; transportValidated: boolean; + connectRequestSent?: boolean; transientPreHelloCleanClose: boolean; connectError?: Error; }; @@ -337,6 +338,8 @@ export type GatewayClientOptions = { requestTimeoutMs?: number; token?: string; bootstrapToken?: string; + /** Prefer one setup credential for the first successful device-auth exchange. */ + preferBootstrapToken?: boolean; deviceToken?: string; password?: string; approvalRuntimeToken?: string; @@ -1037,6 +1040,13 @@ export class GatewayClient { env: this.opts.env, }); } + if (this.opts.preferBootstrapToken) { + // The setup credential is single-use; reconnects must use the stored device token. + this.opts.token = undefined; + this.opts.bootstrapToken = undefined; + this.opts.password = undefined; + this.opts.preferBootstrapToken = false; + } this.tickIntervalMs = typeof helloOk.policy?.tickIntervalMs === "number" ? helloOk.policy.tickIntervalMs : 30_000; if (reconnectWithCurrentNodeProtocol) { @@ -1219,6 +1229,7 @@ export class GatewayClient { phase: context.helloReceived ? "post-hello" : "pre-hello", socketOpened: context.socketOpened, transportValidated: this.transportValidated, + connectRequestSent: context.connectRequestSent, transientPreHelloCleanClose: !context.helloReceived && context.code === 1000 && context.reason === "", ...(context.connectFailure?.error ? { connectError: context.connectFailure.error } : {}), @@ -1336,6 +1347,7 @@ export class GatewayClient { return selectGatewayConnectAuth({ token: this.opts.token, bootstrapToken: this.opts.bootstrapToken, + preferBootstrapToken: this.opts.preferBootstrapToken, deviceToken: this.opts.deviceToken, password: this.opts.password, approvalRuntimeToken: this.approvalRuntimeTokenCompatibilityDisabled diff --git a/packages/gateway-client/src/connect-auth.ts b/packages/gateway-client/src/connect-auth.ts index cb00471033b6..2d4a78d1cc38 100644 --- a/packages/gateway-client/src/connect-auth.ts +++ b/packages/gateway-client/src/connect-auth.ts @@ -43,7 +43,11 @@ export function selectGatewayConnectAuth(params: { const storedToken = normalized(params.storedToken); const stored = { storedToken, storedScopes: params.storedScopes }; if (params.preferBootstrapToken && bootstrapToken) { - return { authBootstrapToken: bootstrapToken, authPassword, ...stored }; + return { + authBootstrapToken: bootstrapToken, + signatureToken: bootstrapToken, + ...stored, + }; } const useRetryToken = params.pendingDeviceTokenRetry === true && diff --git a/packages/gateway-protocol/src/schema/devices.ts b/packages/gateway-protocol/src/schema/devices.ts index 99be458c9195..f0e876f6670d 100644 --- a/packages/gateway-protocol/src/schema/devices.ts +++ b/packages/gateway-protocol/src/schema/devices.ts @@ -113,6 +113,7 @@ export const DevicePairSetupCodeResultSchema = closedObject({ Type.Union([Type.Literal("full"), Type.Literal("limited"), Type.Literal("node")]), ), accessDowngraded: Type.Optional(Type.Boolean()), + expiresAtMs: Type.Optional(Type.Integer({ minimum: 0 })), }); // Wire types derive directly from local schema consts so public d.ts graphs never diff --git a/src/cli/node-cli/gateway-options.test.ts b/src/cli/node-cli/gateway-options.test.ts new file mode 100644 index 000000000000..ecba3cf1f945 --- /dev/null +++ b/src/cli/node-cli/gateway-options.test.ts @@ -0,0 +1,62 @@ +import { describe, expect, it } from "vitest"; +import { encodePairingSetupCode } from "../../pairing/setup-code.js"; +import { resolveNodeGatewayOptions, resolveNodePairGatewayOptions } from "./gateway-options.js"; + +describe("node gateway options", () => { + it("preserves ordered pairing endpoint candidates and pins only the direct endpoint", () => { + const pair = resolveNodePairGatewayOptions( + encodePairingSetupCode({ + url: "wss://192.168.1.20:8443/openclaw-gw", + urls: ["wss://192.168.1.20:8443/openclaw-gw", "wss://gateway.tailnet.example/tailnet-gw"], + bootstrapToken: "bootstrap-123", + tlsFingerprint: "sha256:direct-leaf", + }), + ); + + expect(resolveNodeGatewayOptions({}, null, pair).gatewayCandidates).toEqual([ + { + host: "192.168.1.20", + port: 8443, + contextPath: "/openclaw-gw", + tls: true, + tlsFingerprint: "sha256:direct-leaf", + }, + { + host: "gateway.tailnet.example", + port: 443, + contextPath: "/tailnet-gw", + tls: true, + }, + ]); + expect(resolveNodeGatewayOptions({}, null, pair).contextPath).toBe("/openclaw-gw"); + }); + + it("keeps origin-only pairing endpoints pathless", () => { + const pair = resolveNodePairGatewayOptions( + encodePairingSetupCode({ + url: "wss://gateway.example", + bootstrapToken: "bootstrap-123", + }), + ); + + expect(resolveNodeGatewayOptions({}, null, pair)).toMatchObject({ + contextPath: undefined, + gatewayCandidates: [{ host: "gateway.example", port: 443, tls: true }], + }); + }); + + it("collapses pairing candidates when an endpoint flag is explicit", () => { + const pair = resolveNodePairGatewayOptions( + encodePairingSetupCode({ + url: "ws://192.168.1.20:18789", + urls: ["ws://192.168.1.20:18789", "wss://gateway.tailnet.example"], + bootstrapToken: "bootstrap-123", + }), + ); + + expect(resolveNodeGatewayOptions({ host: "manual.example" }, null, pair)).toMatchObject({ + host: "manual.example", + gatewayCandidates: undefined, + }); + }); +}); diff --git a/src/cli/node-cli/gateway-options.ts b/src/cli/node-cli/gateway-options.ts index f4970240803d..e7d48040d4f8 100644 --- a/src/cli/node-cli/gateway-options.ts +++ b/src/cli/node-cli/gateway-options.ts @@ -1,5 +1,6 @@ import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce"; -import type { NodeHostConfig } from "../../node-host/config.js"; +import type { NodeHostConfig, NodeHostGatewayConfig } from "../../node-host/config.js"; +import { decodePairingSetupCode } from "../../pairing/setup-code.js"; import { parsePort } from "../daemon-cli/shared.js"; type NodeGatewayOptions = { @@ -10,29 +11,84 @@ type NodeGatewayOptions = { tlsFingerprint?: string; }; +type NodePairGatewayOptions = { + host: string; + port: number; + contextPath?: string; + tls: boolean; + tlsFingerprint?: string; + bootstrapToken: string; + candidates: NodeHostGatewayConfig[]; +}; + +function gatewayConfigFromUrl(url: string, tlsFingerprint?: string): NodeHostGatewayConfig { + const parsed = new URL(url); + const tls = parsed.protocol === "wss:"; + return { + host: parsed.hostname, + port: parsed.port ? Number.parseInt(parsed.port, 10) : tls ? 443 : 80, + ...(parsed.pathname !== "/" ? { contextPath: parsed.pathname } : {}), + tls, + ...(tlsFingerprint ? { tlsFingerprint } : {}), + }; +} + +export function resolveNodePairGatewayOptions(input: string): NodePairGatewayOptions { + const payload = decodePairingSetupCode(input); + const candidates = (payload.urls ?? [payload.url]).map((url) => + gatewayConfigFromUrl(url, url === payload.url ? payload.tlsFingerprint : undefined), + ); + const primary = candidates[0]!; + return { + host: primary.host ?? "127.0.0.1", + port: primary.port ?? 18789, + ...(primary.contextPath ? { contextPath: primary.contextPath } : {}), + tls: primary.tls ?? false, + ...(primary.tlsFingerprint ? { tlsFingerprint: primary.tlsFingerprint } : {}), + bootstrapToken: payload.bootstrapToken, + candidates, + }; +} + export function resolveNodeGatewayOptions( options: NodeGatewayOptions, config: NodeHostConfig | null, + pair?: NodePairGatewayOptions, ) { - const savedHost = config?.gateway?.host || "127.0.0.1"; - const savedPort = config?.gateway?.port ?? 18789; - const host = normalizeOptionalString(options.host) || savedHost; - const port = options.port === undefined ? savedPort : parsePort(options.port); - const endpointChanged = host !== savedHost || (port !== null && port !== savedPort); + const baselineHost = pair?.host ?? config?.gateway?.host ?? "127.0.0.1"; + const baselinePort = pair?.port ?? config?.gateway?.port ?? 18789; + const host = normalizeOptionalString(options.host) || baselineHost; + const port = options.port === undefined ? baselinePort : parsePort(options.port); + const endpointChanged = host !== baselineHost || (port !== null && port !== baselinePort); + const baselineTlsFingerprint = pair?.tlsFingerprint ?? config?.gateway?.tlsFingerprint; + const baselineTls = pair?.tls ?? config?.gateway?.tls; const tlsFingerprint = options.tls === false ? undefined : (normalizeOptionalString(options.tlsFingerprint) ?? - (endpointChanged ? undefined : config?.gateway?.tlsFingerprint)); + (endpointChanged ? undefined : baselineTlsFingerprint)); const tls = typeof options.tls === "boolean" ? options.tls - : Boolean(tlsFingerprint) || (endpointChanged ? undefined : config?.gateway?.tls); + : Boolean(tlsFingerprint) || (endpointChanged ? undefined : baselineTls); const contextPath = normalizeOptionalString(options.contextPath) ?? (options.contextPath !== undefined || endpointChanged ? undefined - : config?.gateway?.contextPath); + : (pair?.contextPath ?? config?.gateway?.contextPath)); + const hasExplicitEndpoint = + options.host !== undefined || + options.port !== undefined || + options.contextPath !== undefined || + options.tls !== undefined || + options.tlsFingerprint !== undefined; - return { host, port, contextPath, tls, tlsFingerprint }; + return { + host, + port, + contextPath, + tls, + tlsFingerprint, + gatewayCandidates: pair && !hasExplicitEndpoint ? pair.candidates : undefined, + }; } diff --git a/src/cli/node-cli/register.test.ts b/src/cli/node-cli/register.test.ts index ce1eda947167..795b7e69e2ed 100644 --- a/src/cli/node-cli/register.test.ts +++ b/src/cli/node-cli/register.test.ts @@ -1,6 +1,7 @@ // Node CLI register tests cover node command registration and option wiring. import { Command } from "commander"; import { beforeEach, describe, expect, it, vi } from "vitest"; +import { encodePairingSetupCode } from "../../pairing/setup-code.js"; import { registerNodeCli } from "./register.js"; type LoadNodeHostConfig = typeof import("../../node-host/config.js").loadNodeHostConfig; @@ -106,6 +107,86 @@ describe("registerNodeCli", () => { ); }); + it("derives the node endpoint, TLS pin, and bootstrap credential from --pair", async () => { + const setupCode = encodePairingSetupCode({ + url: "wss://gateway.example:8443/openclaw-gw", + bootstrapToken: "bootstrap-123", + tlsFingerprint: "sha256:pair-leaf", + }); + + await createProgram().parseAsync(["node", "run", "--pair", `oc-pair://${setupCode}`], { + from: "user", + }); + + expect(daemonMocks.runNodeHost).toHaveBeenCalledWith( + expect.objectContaining({ + gatewayHost: "gateway.example", + gatewayPort: 8443, + gatewayContextPath: "/openclaw-gw", + gatewayTls: true, + gatewayTlsFingerprint: "sha256:pair-leaf", + gatewayCandidates: [ + { + host: "gateway.example", + port: 8443, + contextPath: "/openclaw-gw", + tls: true, + tlsFingerprint: "sha256:pair-leaf", + }, + ], + gatewayBootstrapToken: "bootstrap-123", + preferGatewayBootstrapToken: true, + }), + ); + }); + + it("lets explicit gateway flags override --pair values", async () => { + const setupCode = encodePairingSetupCode({ + url: "wss://paired.example:8443", + bootstrapToken: "bootstrap-123", + tlsFingerprint: "sha256:pair-leaf", + }); + + await createProgram().parseAsync( + [ + "node", + "run", + "--pair", + setupCode, + "--host", + "explicit.example", + "--port", + "19000", + "--tls-fingerprint", + "sha256:explicit-leaf", + ], + { from: "user" }, + ); + + expect(daemonMocks.runNodeHost).toHaveBeenCalledWith( + expect.objectContaining({ + gatewayHost: "explicit.example", + gatewayPort: 19000, + gatewayTls: true, + gatewayTlsFingerprint: "sha256:explicit-leaf", + gatewayCandidates: undefined, + gatewayBootstrapToken: "bootstrap-123", + }), + ); + }); + + it("rejects an invalid --pair value before loading node state", async () => { + await createProgram().parseAsync(["node", "run", "--pair", "not-a-setup-code"], { + from: "user", + }); + + expect(daemonMocks.runNodeHost).not.toHaveBeenCalled(); + expect(daemonMocks.loadNodeHostConfig).not.toHaveBeenCalled(); + expect(daemonMocks.defaultRuntime.error).toHaveBeenCalledWith( + expect.stringContaining("Invalid pairing setup"), + ); + }); + it.each([ ["host", ["--host", "10.0.0.2"]], ["port", ["--port", "19001"]], diff --git a/src/cli/node-cli/register.ts b/src/cli/node-cli/register.ts index dce0bc4191e8..4816ee39b8a5 100644 --- a/src/cli/node-cli/register.ts +++ b/src/cli/node-cli/register.ts @@ -16,7 +16,7 @@ import { runNodeDaemonStop, runNodeDaemonUninstall, } from "./daemon.js"; -import { resolveNodeGatewayOptions } from "./gateway-options.js"; +import { resolveNodeGatewayOptions, resolveNodePairGatewayOptions } from "./gateway-options.js"; import { runNodeIdentityShow } from "./identity.js"; export function registerNodeCli(program: Command) { @@ -48,6 +48,10 @@ export function registerNodeCli(program: Command) { node .command("run") .description("Run the headless node host (foreground)") + .option( + "--pair ", + "Pair with a setup code or oc-pair URL; explicit gateway flags take precedence", + ) .option("--host ", "Gateway host") .option("--port ", "Gateway port") .option("--context-path ", "Gateway WebSocket context path (e.g. /openclaw-gw)") @@ -59,11 +63,17 @@ export function registerNodeCli(program: Command) { .option("--share-installed-apps", "Share installed macOS applications with the Gateway") .option("--no-share-installed-apps", "Disable installed application sharing") .action(async (opts) => { + let pair; + try { + pair = opts.pair ? resolveNodePairGatewayOptions(opts.pair) : undefined; + } catch (error) { + defaultRuntime.error(error instanceof Error ? error.message : String(error)); + defaultRuntime.exit(1); + return; + } const existing = await loadNodeHostConfig(); - const { host, port, contextPath, tls, tlsFingerprint } = resolveNodeGatewayOptions( - opts, - existing, - ); + const { host, port, contextPath, tls, tlsFingerprint, gatewayCandidates } = + resolveNodeGatewayOptions(opts, existing, pair); if (port === null) { defaultRuntime.error(formatInvalidPortOption("--port")); defaultRuntime.exit(1); @@ -80,6 +90,9 @@ export function registerNodeCli(program: Command) { gatewayTls: tls, gatewayTlsFingerprint: tlsFingerprint, gatewayContextPath: contextPath, + gatewayCandidates, + gatewayBootstrapToken: pair?.bootstrapToken, + preferGatewayBootstrapToken: pair !== undefined, nodeId: opts.nodeId, displayName: opts.displayName, installedAppsSharing: opts.shareInstalledApps, diff --git a/src/cli/qr-cli.test.ts b/src/cli/qr-cli.test.ts index 6d5478056d8a..62bec3649b6d 100644 --- a/src/cli/qr-cli.test.ts +++ b/src/cli/qr-cli.test.ts @@ -159,6 +159,7 @@ describe("registerQrCli", () => { const expected = encodePairingSetupCode({ url, bootstrapToken: "bootstrap-123", + expiresAtMs: 123, }); expect(runtime.log).toHaveBeenCalledWith(expected); } @@ -209,6 +210,7 @@ describe("registerQrCli", () => { const expected = encodePairingSetupCode({ url: "ws://127.0.0.1:18789", bootstrapToken: "bootstrap-123", + expiresAtMs: 123, }); expect(runtime.log).toHaveBeenCalledWith(expected); expect(renderTerminal).not.toHaveBeenCalled(); @@ -290,6 +292,7 @@ describe("registerQrCli", () => { const expected = encodePairingSetupCode({ url: "ws://127.0.0.1:18789", bootstrapToken: "bootstrap-123", + expiresAtMs: 123, }); expect(renderTerminal).toHaveBeenCalledWith(expected, { small: true }); const output = runtimeLog.mock.calls.map((call) => readRuntimeCallText(call)).join("\n"); @@ -495,6 +498,7 @@ describe("registerQrCli", () => { const expected = encodePairingSetupCode({ url: "wss://remote.example.com:444", bootstrapToken: "bootstrap-123", + expiresAtMs: 123, }); expect(runtime.log).toHaveBeenCalledWith(expected); const request = resolveCommandSecretRefsViaGateway.mock.calls[0]?.[0] as @@ -557,6 +561,7 @@ describe("registerQrCli", () => { const expected = encodePairingSetupCode({ url: "wss://remote.example.com:444", bootstrapToken: "bootstrap-123", + expiresAtMs: 123, }); expect(runtime.log).toHaveBeenCalledWith(expected); }); diff --git a/src/cli/qr-cli.ts b/src/cli/qr-cli.ts index adc9b900cb6e..29b808c82184 100644 --- a/src/cli/qr-cli.ts +++ b/src/cli/qr-cli.ts @@ -7,6 +7,7 @@ import type { OpenClawConfig } from "../config/types.openclaw.js"; import { hasConfiguredSecretInput } from "../config/types.secrets.js"; import { trimToUndefined } from "../gateway/credentials.js"; import { resolveRequiredConfiguredSecretRefInputString } from "../gateway/resolve-configured-secret-input-string.js"; +import { loadGatewayTlsRuntime } from "../infra/tls/gateway.js"; import { renderQrTerminal } from "../media/qr-terminal.ts"; import { resolvePairingSetupFromConfig, encodePairingSetupCode } from "../pairing/setup-code.js"; import { runCommandWithTimeout } from "../process/exec.js"; @@ -220,6 +221,10 @@ export function registerQrCli(program: Command) { await runCommandWithTimeout(argv, { timeoutMs: runOpts.timeoutMs, }), + loadLocalTlsFingerprint: async () => { + const tls = await loadGatewayTlsRuntime(cfg.gateway?.tls); + return tls.enabled ? tls.fingerprintSha256 : undefined; + }, }); if (!resolved.ok) { diff --git a/src/cli/resume-cli.test.ts b/src/cli/resume-cli.test.ts index 5bbabc982a24..439a7154a45f 100644 --- a/src/cli/resume-cli.test.ts +++ b/src/cli/resume-cli.test.ts @@ -1,4 +1,9 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; +import type { DeviceAuthTokenRecord } from "../../packages/gateway-client/src/client.js"; +import { + GATEWAY_CLIENT_MODES, + GATEWAY_CLIENT_NAMES, +} from "../../packages/gateway-protocol/src/client-info.js"; import { ConnectErrorDetailCodes } from "../../packages/gateway-protocol/src/connect-error-details.js"; import { startMinimalRealGateway } from "../gateway/minimal-gateway.test-helpers.js"; import type { TuiSessionList } from "../tui/tui-backend.js"; @@ -218,4 +223,50 @@ describe("real Gateway session boundary", () => { }), ); }); + + it("retires the one-use bootstrap credential before a real-wire reconnect", async () => { + const { GatewayClient } = + await vi.importActual("../gateway/client.js"); + const authState: { value: DeviceAuthTokenRecord | null } = { value: null }; + const storeDeviceAuthToken = vi.fn(({ token, scopes }: { token: string; scopes: string[] }) => { + authState.value = { token, scopes }; + }); + let helloCount = 0; + const client = new GatewayClient({ + url: harness.url, + bootstrapToken: await harness.issueNodeBootstrapToken(), + preferBootstrapToken: true, + role: "node", + scopes: [], + clientName: GATEWAY_CLIENT_NAMES.NODE_HOST, + clientVersion: "test", + platform: "test", + mode: GATEWAY_CLIENT_MODES.NODE, + deviceIdentity: harness.createDeviceIdentity("reconnect"), + hostDeps: { + loadDeviceAuthToken: () => authState.value, + storeDeviceAuthToken, + }, + onHelloOk: () => { + helloCount += 1; + }, + }); + client.start(); + try { + await vi.waitFor(() => expect(helloCount).toBe(1), { timeout: 5_000 }); + expect(storeDeviceAuthToken).toHaveBeenCalledOnce(); + expect(storeDeviceAuthToken).toHaveBeenCalledWith( + expect.objectContaining({ + token: expect.stringMatching(/\S/), + scopes: expect.any(Array), + }), + ); + expect(authState.value?.token).toBeTruthy(); + + await harness.restart(); + await vi.waitFor(() => expect(helloCount).toBe(2), { timeout: 5_000 }); + } finally { + await client.stopAndWait(); + } + }); }); diff --git a/src/gateway/call.test.ts b/src/gateway/call.test.ts index d27a71674e46..d96a49c7a88b 100644 --- a/src/gateway/call.test.ts +++ b/src/gateway/call.test.ts @@ -125,6 +125,7 @@ function startStubGatewayClient() { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: true, }); lastClientOptions?.onHelloOk?.(makeStubGatewayHello()); @@ -133,12 +134,14 @@ function startStubGatewayClient() { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: true, }); lastClientOptions?.onClose?.(1000, "", { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: true, }); } else if (startMode === "connect-error") { diff --git a/src/gateway/client-callsites.guard.test.ts b/src/gateway/client-callsites.guard.test.ts index cbdff0114b62..7342512c91aa 100644 --- a/src/gateway/client-callsites.guard.test.ts +++ b/src/gateway/client-callsites.guard.test.ts @@ -16,7 +16,7 @@ const ALLOWED_GATEWAY_CLIENT_CALLSITES = new Set([ "src/gateway/gateway-cli-backend.live-helpers.ts", "src/gateway/operator-approvals-client.ts", "src/gateway/probe.ts", - "src/node-host/runner.ts", + "src/node-host/gateway-candidate-connection.ts", "src/tui/gateway-chat.ts", ]); diff --git a/src/gateway/client.test.ts b/src/gateway/client.test.ts index a2fee29aa28e..9c8227ed9b3d 100644 --- a/src/gateway/client.test.ts +++ b/src/gateway/client.test.ts @@ -745,6 +745,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: false, transportValidated: false, + connectRequestSent: false, transientPreHelloCleanClose: false, }, ); @@ -768,6 +769,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: false, transportValidated: false, + connectRequestSent: false, transientPreHelloCleanClose: false, }); client.stop(); @@ -785,6 +787,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: false, transportValidated: false, + connectRequestSent: false, transientPreHelloCleanClose: false, }); client.stop(); @@ -813,6 +816,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: true, transportValidated: false, + connectRequestSent: false, transientPreHelloCleanClose: false, }); client.stop(); @@ -831,6 +835,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: false, transportValidated: false, + connectRequestSent: false, transientPreHelloCleanClose: false, }); expect(logDebugMock).toHaveBeenCalledWith( @@ -895,6 +900,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: true, }); @@ -981,12 +987,14 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: true, }); expect(onClose).toHaveBeenNthCalledWith(2, 1000, "", { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: true, }); expect(onConnectError).toHaveBeenCalledOnce(); @@ -1106,6 +1114,7 @@ describe("GatewayClient close handling", () => { phase: "pre-hello", socketOpened: false, transportValidated: false, + connectRequestSent: false, transientPreHelloCleanClose: false, }); client.stop(); @@ -1174,6 +1183,7 @@ describe("GatewayClient connect auth payload", () => { maxProtocol?: number; scopes?: string[]; client?: { + id?: string; mode?: string; platform?: string; }; @@ -2401,6 +2411,66 @@ describe("GatewayClient connect auth payload", () => { client.stop(); }); + it("emits only the signed bootstrap credential in a preferred node-host connect frame", () => { + loadDeviceAuthTokenMock.mockReturnValue({ token: "stale-device-token" }); + const signDevicePayload = vi.fn((_privateKeyPem: string, _payload: string) => "signature"); + const client = createClientWithIdentity("device-pairing-bootstrap", vi.fn(), { + token: "shared-token", + bootstrapToken: "bootstrap-token", + password: "shared-password", // pragma: allowlist secret + preferBootstrapToken: true, + role: "node", + mode: GATEWAY_CLIENT_MODES.NODE, + clientName: GATEWAY_CLIENT_NAMES.NODE_HOST, + scopes: [], + hostDeps: { signDevicePayload }, + }); + + const { connect } = startClientAndConnect({ client }); + + expect(connect.params?.client).toMatchObject({ + id: GATEWAY_CLIENT_NAMES.NODE_HOST, + mode: GATEWAY_CLIENT_MODES.NODE, + }); + expect(connect.params?.auth).toEqual({ bootstrapToken: "bootstrap-token" }); + expect(signDevicePayload.mock.calls[0]?.[1]?.split("|")[7]).toBe("bootstrap-token"); + client.stop(); + }); + + it("prefers a paired bootstrap token once, then reconnects with stored device auth", async () => { + loadDeviceAuthTokenMock.mockReturnValue({ token: "stale-device-token" }); + const onHelloOk = vi.fn(); + const client = new GatewayClient({ + url: "ws://127.0.0.1:18789", + token: "shared-token", + bootstrapToken: "bootstrap-token", + password: "shared-password", // pragma: allowlist secret + preferBootstrapToken: true, + onHelloOk, + }); + + const { ws, connect } = startClientAndConnect({ client }); + expect(connectFrameFrom(ws)).toMatchObject({ bootstrapToken: "bootstrap-token" }); + expect(connectFrameFrom(ws).token).toBeUndefined(); + expect(connectFrameFrom(ws).deviceToken).toBeUndefined(); + + loadDeviceAuthTokenMock.mockReturnValue({ token: "issued-device-token" }); + emitHelloOk(ws, connect.id); + await waitForFast(() => expect(onHelloOk).toHaveBeenCalledOnce()); + ws.emitClose(1006, "socket lost"); + await waitForFast(() => expect(wsInstances.length).toBeGreaterThan(1), { timeout: 3_000 }); + const reconnect = getLatestWs(); + reconnect.emitOpen(); + emitConnectChallenge(reconnect, "nonce-reconnect"); + expect(connectFrameFrom(reconnect)).toMatchObject({ + token: "issued-device-token", + deviceToken: "issued-device-token", + }); + expect(connectFrameFrom(reconnect).password).toBeUndefined(); + expect(connectFrameFrom(reconnect).bootstrapToken).toBeUndefined(); + client.stop(); + }); + it("prefers explicit deviceToken over stored device token", () => { loadDeviceAuthTokenMock.mockReturnValue({ token: "stored-device-token", @@ -2600,6 +2670,7 @@ describe("GatewayClient connect auth payload", () => { phase: "pre-hello", socketOpened: true, transportValidated: true, + connectRequestSent: true, transientPreHelloCleanClose: false, }); }); diff --git a/src/gateway/minimal-gateway.test-helpers.ts b/src/gateway/minimal-gateway.test-helpers.ts index 27434a8ed17e..2e641e01aaf4 100644 --- a/src/gateway/minimal-gateway.test-helpers.ts +++ b/src/gateway/minimal-gateway.test-helpers.ts @@ -84,8 +84,9 @@ export async function startMinimalRealGateway( visibility?: import("../config/sessions.js").SessionEntry["visibility"]; }> = [], ) { - const [bootstrap, profiles, sessionStore, testState] = await Promise.all([ + const [bootstrap, deviceIdentity, profiles, sessionStore, testState] = await Promise.all([ import("../infra/device-bootstrap.js"), + import("../infra/device-identity.js"), import("../shared/device-bootstrap-profile.js"), import("../config/sessions/session-accessor.sqlite-entry.js"), import("../test-utils/openclaw-test-state.js"), @@ -112,6 +113,23 @@ export async function startMinimalRealGateway( while (port === 18789) { port = await getFreePort(); } + const startServer = async () => { + const methods = await import("./server-methods.js"); + const original = methods.coreGatewayHandlers["sessions.list"]!; + methods.coreGatewayHandlers["sessions.list"] = async (options) => { + sessionListRequests.push(options.params as Record); + return await original(options); + }; + const gateway = await import("./server.js"); + return await gateway + .startGatewayServer(port, { + auth: { mode: "token", token }, + bind: "loopback", + controlUiEnabled: false, + sidecarStartup: "defer", + }) + .finally(() => (methods.coreGatewayHandlers["sessions.list"] = original)); + }; try { for (const session of sessions) { await sessionStore.upsertSessionEntryCore( @@ -123,21 +141,7 @@ export async function startMinimalRealGateway( { sessionId: session.key, updatedAt: Date.now(), visibility: session.visibility }, ); } - const methods = await import("./server-methods.js"); - const original = methods.coreGatewayHandlers["sessions.list"]!; - methods.coreGatewayHandlers["sessions.list"] = async (options) => { - sessionListRequests.push(options.params as Record); - return await original(options); - }; - const gateway = await import("./server.js"); - server = await gateway - .startGatewayServer(port, { - auth: { mode: "token", token }, - bind: "loopback", - controlUiEnabled: false, - sidecarStartup: "defer", - }) - .finally(() => (methods.coreGatewayHandlers["sessions.list"] = original)); + server = await startServer(); } catch (error) { await state.cleanup(); throw error; @@ -149,18 +153,31 @@ export async function startMinimalRealGateway( sessionListRequests, hellos, connectFailures, - connectBootstrap: async (mismatched = false) => { - const helpers = await import("./test-helpers.js"); - const ws = new WebSocket(`ws://127.0.0.1:${port}`); - clients.push(ws); - const bootstrapToken = ( + issueNodeBootstrapToken: async () => + ( await bootstrap.issueDeviceBootstrapToken({ baseDir: state.stateDir, profile: profiles.NODE_PAIRING_SETUP_BOOTSTRAP_PROFILE, }) - ).token; + ).token, + createDeviceIdentity: (label: string) => + deviceIdentity.loadOrCreateDeviceIdentity({ + path: state.statePath(`device-${label}.sqlite`), + }), + restart: async () => { + await server!.close({ reason: "test reconnect", restartExpectedMs: 0 }); + server = await startServer(); + }, + connectBootstrap: async (mismatched = false) => { + const helpers = await import("./test-helpers.js"); + const ws = new WebSocket(`ws://127.0.0.1:${port}`); + clients.push(ws); + const bootstrapToken = await bootstrap.issueDeviceBootstrapToken({ + baseDir: state.stateDir, + profile: profiles.NODE_PAIRING_SETUP_BOOTSTRAP_PROFILE, + }); const response = await helpers.connectReq(ws, { - bootstrapToken, + bootstrapToken: bootstrapToken.token, ...(mismatched ? { deviceToken: "mismatched-device-token" } : {}), skipDefaultAuth: true, role: "node", diff --git a/src/gateway/probe.test.ts b/src/gateway/probe.test.ts index ad2366402ed2..2a8e6dec7ac8 100644 --- a/src/gateway/probe.test.ts +++ b/src/gateway/probe.test.ts @@ -103,6 +103,7 @@ class MockGatewayClient { phase: "pre-hello", socketOpened: gatewayClientState.socketOpened, transportValidated: gatewayClientState.transportValidated, + connectRequestSent: true, transientPreHelloCleanClose: false, }); } diff --git a/src/gateway/server-kernel-request-runtime.ts b/src/gateway/server-kernel-request-runtime.ts index 3f5c7f03cf42..c30e15196009 100644 --- a/src/gateway/server-kernel-request-runtime.ts +++ b/src/gateway/server-kernel-request-runtime.ts @@ -94,6 +94,7 @@ export async function prepareGatewayKernelRequestRuntime(params: { pluginGatewayContext, getAttachedGatewayMethodRegistry, gatewayInstanceRuntimeRef, + gatewayTls, lifecycle, startupState, clearFallbackGatewayContextForServer, @@ -111,6 +112,7 @@ export async function prepareGatewayKernelRequestRuntime(params: { runtimeState, sessionCompanion, getRuntimeConfig, + gatewayTlsFingerprint: gatewayTls.enabled ? gatewayTls.fingerprintSha256 : undefined, sessionObserver, getMcpAppSandboxPort, ensureSandboxHostPort, diff --git a/src/gateway/server-methods/device-pair-setup.test.ts b/src/gateway/server-methods/device-pair-setup.test.ts index 5e8ea0cd6826..c3a65464f6a1 100644 --- a/src/gateway/server-methods/device-pair-setup.test.ts +++ b/src/gateway/server-methods/device-pair-setup.test.ts @@ -43,6 +43,7 @@ function createOptions( respond, context: { getRuntimeConfig: vi.fn(() => config), + gatewayTlsFingerprint: "sha256:gateway-leaf", }, } as unknown as GatewayRequestHandlerOptions; return { options, respond }; @@ -59,6 +60,7 @@ const okResolution = { urlSource: "remote", access: "full" as const, accessDowngraded: false, + expiresAtMs: 123_456, }; describe("device.pair.setupCode", () => { @@ -95,9 +97,14 @@ describe("device.pair.setupCode", () => { auth: "token", urlSource: "remote", access: "full", + expiresAtMs: 123_456, }); // The bootstrap token only lives inside the (opaque) setup code, never as a field. expect(JSON.stringify(payload)).not.toContain("boot-123"); + expect(mocks.resolvePairingSetupFromConfig).toHaveBeenCalledWith( + expect.any(Object), + expect.objectContaining({ localTlsFingerprint: "sha256:gateway-leaf" }), + ); }); it("reports when plaintext transport limits a requested full-access code", async () => { diff --git a/src/gateway/server-methods/device-pair-setup.ts b/src/gateway/server-methods/device-pair-setup.ts index 8c68721ee0a2..477ac1ad527e 100644 --- a/src/gateway/server-methods/device-pair-setup.ts +++ b/src/gateway/server-methods/device-pair-setup.ts @@ -53,6 +53,7 @@ export const devicePairSetupHandlers: GatewayRequestHandlers = { env: process.env, publicUrl, preferRemoteUrl: params.preferRemoteUrl === true, + localTlsFingerprint: context.gatewayTlsFingerprint, ...(params.bootstrapProfile ? { bootstrapProfile: @@ -89,6 +90,7 @@ export const devicePairSetupHandlers: GatewayRequestHandlers = { auth: resolved.authLabel, urlSource: requestPublicUrl ? "request.publicUrl" : resolved.urlSource, access: resolved.access, + expiresAtMs: resolved.expiresAtMs, ...(resolved.accessDowngraded ? { accessDowngraded: true } : {}), }, undefined, diff --git a/src/gateway/server-methods/shared-types.ts b/src/gateway/server-methods/shared-types.ts index 5b6ad1ffc114..309c286121d1 100644 --- a/src/gateway/server-methods/shared-types.ts +++ b/src/gateway/server-methods/shared-types.ts @@ -188,6 +188,8 @@ type GatewayKernelContext = { cron: GatewayCronServiceContract; cronStorePath: string; getRuntimeConfig: () => OpenClawConfig; + /** Prepared listener certificate pin; undefined when Gateway TLS is disabled. */ + gatewayTlsFingerprint?: string; sessionCompanion?: import("../session-companion.js").SessionCompanionService; sessionObserver?: SessionObserverService; resolveTerminalLaunchPolicy: (agentId?: string) => TerminalLaunchResolution; diff --git a/src/gateway/server-request-context.ts b/src/gateway/server-request-context.ts index 91e33b5f7d9f..f1372f4c19b5 100644 --- a/src/gateway/server-request-context.ts +++ b/src/gateway/server-request-context.ts @@ -31,6 +31,7 @@ type GatewayRequestContextParams = { "cronState" | "controlUiSessionPullRequests" | "sessionViewerPresence" >; getRuntimeConfig: GatewayRequestContext["getRuntimeConfig"]; + gatewayTlsFingerprint?: GatewayRequestContext["gatewayTlsFingerprint"]; sessionCompanion: SessionCompanionService; sessionObserver: SessionObserverService; getMcpAppSandboxPort?: GatewayRequestContext["getMcpAppSandboxPort"]; @@ -173,6 +174,7 @@ export function createGatewayRequestContext( return params.runtimeState.cronState.storePath; }, getRuntimeConfig: params.getRuntimeConfig, + gatewayTlsFingerprint: params.gatewayTlsFingerprint, controlUiSessionPullRequests: params.runtimeState.controlUiSessionPullRequests, sessionViewerPresence: params.runtimeState.sessionViewerPresence, sessionCompanion: params.sessionCompanion, diff --git a/src/node-host/gateway-candidate-connection.test.ts b/src/node-host/gateway-candidate-connection.test.ts new file mode 100644 index 000000000000..4ed09ceb996e --- /dev/null +++ b/src/node-host/gateway-candidate-connection.test.ts @@ -0,0 +1,179 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { GatewayClientOptions } from "../gateway/client.js"; +import { createNodeHostGatewayCandidateConnection } from "./gateway-candidate-connection.js"; + +const mocks = vi.hoisted(() => ({ + options: [] as GatewayClientOptions[], + clients: [] as Array<{ + request: ReturnType; + start: ReturnType; + stop: ReturnType; + updateNodeManifest: ReturnType; + }>, +})); + +vi.mock("../gateway/client.js", () => ({ + GatewayClient: function GatewayClient(options: GatewayClientOptions) { + const client = { + request: vi.fn(async () => ({ url: options.url })), + start: vi.fn(), + stop: vi.fn(), + updateNodeManifest: vi.fn(), + }; + mocks.options.push(options); + mocks.clients.push(client); + return client; + }, +})); + +const candidates = [ + { host: "192.168.1.20", port: 18789, contextPath: "/openclaw-gw", tls: false }, + { host: "gateway.tailnet.example", port: 443, tls: true }, +]; + +function createConnection() { + const callbacks = { + onEvent: vi.fn(), + onHelloOk: vi.fn(), + onConnectError: vi.fn(), + onReconnectPaused: vi.fn(), + onClose: vi.fn(), + onWinningCandidate: vi.fn(), + }; + return { + callbacks, + connection: createNodeHostGatewayCandidateConnection({ + candidates, + clientOptions: {}, + ...callbacks, + }), + }; +} + +describe("gateway candidate connection", () => { + beforeEach(() => { + mocks.options.length = 0; + mocks.clients.length = 0; + vi.clearAllMocks(); + }); + + it("rotates only before hello, fences stale callbacks, and forwards through the winner", async () => { + const { callbacks, connection } = createConnection(); + connection.start(); + + expect(mocks.options[0]?.url).toBe("ws://192.168.1.20:18789/openclaw-gw"); + expect(mocks.clients[0]?.start).toHaveBeenCalledOnce(); + mocks.options[0]?.onClose?.(1006, "transport unavailable", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + connectRequestSent: false, + transientPreHelloCleanClose: false, + }); + await vi.waitFor(() => expect(mocks.clients).toHaveLength(2)); + + expect(mocks.clients[0]?.stop).toHaveBeenCalledOnce(); + expect(mocks.options[1]?.url).toBe("wss://gateway.tailnet.example:443"); + expect(mocks.clients[1]?.start).toHaveBeenCalledOnce(); + + mocks.options[0]?.onEvent?.({ type: "event", event: "stale" }); + mocks.options[0]?.onHelloOk?.({} as never); + mocks.options[0]?.onClose?.(1006, "stale close", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + connectRequestSent: false, + transientPreHelloCleanClose: false, + }); + expect(callbacks.onEvent).not.toHaveBeenCalled(); + expect(callbacks.onHelloOk).not.toHaveBeenCalled(); + expect(callbacks.onWinningCandidate).not.toHaveBeenCalled(); + expect(mocks.clients).toHaveLength(2); + + const activeEvent = { type: "event", event: "active" } as const; + mocks.options[1]?.onEvent?.(activeEvent); + mocks.options[1]?.onHelloOk?.({} as never); + mocks.options[1]?.onHelloOk?.({} as never); + expect(callbacks.onEvent).toHaveBeenCalledWith(activeEvent); + expect(callbacks.onWinningCandidate).toHaveBeenCalledOnce(); + expect(callbacks.onWinningCandidate).toHaveBeenCalledWith(candidates[1]); + + await connection.request("node.test", { active: true }, undefined); + connection.updateNodeManifest({ caps: ["mcp"], commands: ["mcp.tools.call.v1"] }); + expect(mocks.clients[0]?.request).not.toHaveBeenCalled(); + expect(mocks.clients[1]?.request).toHaveBeenCalledWith( + "node.test", + { active: true }, + undefined, + ); + expect(mocks.clients[1]?.updateNodeManifest).toHaveBeenCalledWith({ + caps: ["mcp"], + commands: ["mcp.tools.call.v1"], + }); + }); + + it("does not rotate after the connect request was sent", async () => { + createConnection(); + + mocks.options[0]?.onClose?.(1008, "connect failed", { + phase: "pre-hello", + socketOpened: true, + transportValidated: true, + connectRequestSent: true, + transientPreHelloCleanClose: false, + }); + await Promise.resolve(); + + expect(mocks.clients).toHaveLength(1); + }); + + it("promotes a candidate after hello instead of replaying setup auth on another endpoint", async () => { + const { callbacks } = createConnection(); + + mocks.options[0]?.onHelloOk?.({} as never); + mocks.options[0]?.onClose?.(1006, "later reconnect transport failure", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + connectRequestSent: false, + transientPreHelloCleanClose: false, + }); + await Promise.resolve(); + + expect(callbacks.onWinningCandidate).toHaveBeenCalledWith(candidates[0]); + expect(mocks.clients).toHaveLength(1); + }); + + it("carries a pre-hello manifest update into the next candidate", async () => { + const { connection } = createConnection(); + const manifest = { caps: ["mcp"], commands: ["mcp.tools.call.v1"] }; + + connection.updateNodeManifest(manifest); + mocks.options[0]?.onClose?.(1006, "transport unavailable", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + connectRequestSent: false, + transientPreHelloCleanClose: false, + }); + await vi.waitFor(() => expect(mocks.clients).toHaveLength(2)); + + expect(mocks.clients[1]?.updateNodeManifest).toHaveBeenCalledWith(manifest); + }); + + it("does not create the queued candidate after stop", async () => { + const { connection } = createConnection(); + + mocks.options[0]?.onClose?.(1006, "transport unavailable", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + connectRequestSent: false, + transientPreHelloCleanClose: false, + }); + connection.stop(); + await Promise.resolve(); + + expect(mocks.clients).toHaveLength(1); + }); +}); diff --git a/src/node-host/gateway-candidate-connection.ts b/src/node-host/gateway-candidate-connection.ts new file mode 100644 index 000000000000..df34108a29e9 --- /dev/null +++ b/src/node-host/gateway-candidate-connection.ts @@ -0,0 +1,152 @@ +import { + GatewayClient, + type GatewayClientCloseInfo, + type GatewayClientOptions, + type GatewayClientRequestOptions, + type GatewayReconnectPausedInfo, +} from "../gateway/client.js"; +import type { NodeHostGatewayConfig } from "./config.js"; + +type GatewayCandidateEvent = Parameters>[0]; +type GatewayCandidateHello = Parameters>[0]; + +type CandidateConnectionOptions = Omit< + GatewayClientOptions, + | "url" + | "tlsFingerprint" + | "onEvent" + | "onHelloOk" + | "onConnectError" + | "onReconnectPaused" + | "onClose" +>; + +type GatewayCandidateConnectionParams = { + candidates: readonly NodeHostGatewayConfig[]; + clientOptions: CandidateConnectionOptions; + onEvent: (event: GatewayCandidateEvent) => void; + onHelloOk: (hello: GatewayCandidateHello, url: string) => void; + onConnectError: (error: Error) => void; + onReconnectPaused: (info: GatewayReconnectPausedInfo) => void; + onClose: (code: number, reason: string, info?: GatewayClientCloseInfo) => void; + onWinningCandidate: (candidate: NodeHostGatewayConfig) => void; +}; + +function formatGatewayCandidateUrl(gateway: NodeHostGatewayConfig): string { + const host = gateway.host ?? "127.0.0.1"; + const urlHost = + host.includes(":") && !(host.startsWith("[") && host.endsWith("]")) ? `[${host}]` : host; + const port = gateway.port ?? 18789; + const scheme = gateway.tls ? "wss" : "ws"; + const contextPath = gateway.contextPath + ? gateway.contextPath.startsWith("/") + ? gateway.contextPath + : `/${gateway.contextPath}` + : ""; + return `${scheme}://${urlHost}:${port}${contextPath}`; +} + +function canTryNextGatewayCandidate(info: GatewayClientCloseInfo | undefined): boolean { + return info?.phase === "pre-hello" && info.connectRequestSent === false; +} + +export function createNodeHostGatewayCandidateConnection(params: GatewayCandidateConnectionParams) { + if (params.candidates.length === 0) { + throw new Error("node host gateway candidate list cannot be empty"); + } + + let currentCandidateIndex = 0; + let stopped = false; + let winnerSelected = params.candidates.length === 1; + let latestManifest: { caps: string[]; commands: string[] } | undefined; + let currentClient = createCandidateClient(currentCandidateIndex); + + function createCandidateClient(candidateIndex: number): GatewayClient { + const candidate = params.candidates[candidateIndex]; + if (!candidate) { + throw new Error(`node host gateway candidate ${candidateIndex} is unavailable`); + } + const url = formatGatewayCandidateUrl(candidate); + const candidateClient = new GatewayClient({ + ...params.clientOptions, + url, + tlsFingerprint: candidate.tlsFingerprint, + onEvent: (event) => { + if (currentCandidateIndex === candidateIndex) { + params.onEvent(event); + } + }, + onHelloOk: (hello) => { + if (currentCandidateIndex !== candidateIndex) { + return; + } + if (!winnerSelected) { + winnerSelected = true; + params.onWinningCandidate(candidate); + } + params.onHelloOk(hello, url); + }, + onConnectError: (error) => { + if (currentCandidateIndex === candidateIndex) { + params.onConnectError(error); + } + }, + onReconnectPaused: (info) => { + if (currentCandidateIndex === candidateIndex) { + params.onReconnectPaused(info); + } + }, + onClose: (code, reason, info) => { + if (currentCandidateIndex !== candidateIndex) { + return; + } + params.onClose(code, reason, info); + const nextCandidateIndex = candidateIndex + 1; + if ( + stopped || + // A successful hello redeems setup credentials and promotes this + // endpoint. Its own reconnect path owns durable device auth from here. + winnerSelected || + nextCandidateIndex >= params.candidates.length || + !canTryNextGatewayCandidate(info) + ) { + return; + } + currentCandidateIndex = nextCandidateIndex; + candidateClient.stop(); + queueMicrotask(() => { + if (stopped || currentCandidateIndex !== nextCandidateIndex) { + return; + } + currentClient = createCandidateClient(nextCandidateIndex); + currentClient.start(); + }); + }, + }); + if (latestManifest) { + candidateClient.updateNodeManifest(latestManifest); + } + return candidateClient; + } + + return { + start(): void { + currentClient.start(); + }, + stop(): void { + stopped = true; + currentClient.stop(); + }, + request>( + ...requestArgs: [method: string, params?: unknown, options?: GatewayClientRequestOptions] + ): Promise { + return currentClient.request(...requestArgs); + }, + updateNodeManifest(manifest: { caps: string[]; commands: string[] }): void { + // Availability may change before the first hello. Every later candidate + // must start with the newest manifest rather than the constructor snapshot. + latestManifest = manifest; + currentClient.updateNodeManifest(manifest); + }, + }; +} diff --git a/src/node-host/runner.test.ts b/src/node-host/runner.test.ts index 6801e98d29d5..e796cdaf826f 100644 --- a/src/node-host/runner.test.ts +++ b/src/node-host/runner.test.ts @@ -15,6 +15,7 @@ const mocks = vi.hoisted(() => ({ capturedConfiguredGatewayConfigs: [] as Array<{ contextPath?: string }>, capturedGatewayClients: [] as Array<{ request: Mock<(method: string, params?: unknown) => Promise>; + start: ReturnType; stop: ReturnType; updateNodeManifest: ReturnType; }>, @@ -30,6 +31,9 @@ const mocks = vi.hoisted(() => ({ availabilityChanged: undefined as (() => void) | undefined, normalizedPath: null as string | null, resolvedExecutables: new Map(), + runtimeClient: undefined as + | { request: (method: string, params?: unknown) => Promise } + | undefined, closeMcpManager: vi.fn(async () => undefined), runStartupMigrations: vi.fn(async () => undefined), configureNodeHost: vi.fn(async (params: Parameters[0]) => { @@ -76,6 +80,7 @@ vi.mock("../gateway/client.js", async (importOriginal) => { GatewayClient: function GatewayClient(opts: GatewayClientOptions) { const client = { request: vi.fn(async () => ({})), + start: vi.fn(), stop: vi.fn(), updateNodeManifest: vi.fn(), }; @@ -171,7 +176,10 @@ vi.mock("./runtime.js", async (importOriginal) => { return { manifest: { caps: [], commands: [], pathEnv: process.env.PATH ?? "" }, initialInventory: { skills: [], pluginTools: [] }, - start: () => mocks.activeRuntime, + start: (params) => { + mocks.runtimeClient = params.client; + return mocks.activeRuntime; + }, }; }, }; @@ -207,6 +215,7 @@ describe("runNodeHost", () => { mocks.availabilityChanged = undefined; mocks.normalizedPath = null; mocks.resolvedExecutables.clear(); + mocks.runtimeClient = undefined; vi.clearAllMocks(); mocks.getRuntimeConfig.mockReturnValue({ gateway: { handshakeTimeoutMs: 1_000 }, @@ -246,6 +255,84 @@ describe("runNodeHost", () => { }, ); + it("passes a paired bootstrap credential with first-connect preference", async () => { + await expect( + runNodeHost({ + gatewayHost: "gateway.example", + gatewayPort: 443, + gatewayTls: true, + gatewayBootstrapToken: "bootstrap-123", + preferGatewayBootstrapToken: true, + }), + ).rejects.toThrow("event loop readiness timeout"); + + expect(lastCapturedOptions()).toMatchObject({ + bootstrapToken: "bootstrap-123", + preferBootstrapToken: true, + }); + expect(lastCapturedOptions()?.token).toBeUndefined(); + expect(mocks.resolveGatewayCredentialsWithSecretInputs).not.toHaveBeenCalled(); + }); + + it("persists the pairing candidate that completes the handshake", async () => { + mocks.useFakeRuntime = true; + mocks.startGatewayClientWhenEventLoopReady.mockResolvedValueOnce({ + ready: true, + aborted: false, + elapsedMs: 0, + }); + const processOnceSpy = vi.spyOn(process, "once"); + const previousExitCode = process.exitCode; + try { + const running = runNodeHost({ + gatewayHost: "192.168.1.20", + gatewayPort: 18789, + gatewayBootstrapToken: "bootstrap-123", + preferGatewayBootstrapToken: true, + gatewayCandidates: [ + { host: "192.168.1.20", port: 18789, tls: false }, + { host: "gateway.tailnet.example", port: 443, tls: true }, + ], + }); + await vi.waitFor(() => expect(mocks.capturedGatewayClients).toHaveLength(1)); + + const firstOptions = mocks.capturedGatewayClientOptions[0]; + firstOptions?.onClose?.(1006, "transport unavailable", { + phase: "pre-hello", + socketOpened: false, + transportValidated: false, + connectRequestSent: false, + transientPreHelloCleanClose: false, + }); + await vi.waitFor(() => expect(mocks.capturedGatewayClients).toHaveLength(2)); + + expect(mocks.capturedGatewayClientOptions[1]?.url).toBe("wss://gateway.tailnet.example:443"); + + mocks.capturedGatewayClientOptions[1]?.onHelloOk?.({} as never); + await vi.waitFor(() => expect(mocks.configureNodeHost).toHaveBeenCalledTimes(2)); + expect(mocks.capturedConfiguredGatewayConfigs[1]).toEqual({ + host: "gateway.tailnet.example", + port: 443, + tls: true, + }); + + await vi.waitFor(() => + expect(processOnceSpy.mock.calls.some(([event]) => event === "SIGTERM")).toBe(true), + ); + const onSigterm = processOnceSpy.mock.calls.find(([event]) => event === "SIGTERM")?.[1]; + onSigterm?.("SIGTERM"); + await running; + } finally { + for (const [event, listener] of processOnceSpy.mock.calls) { + if ((event === "SIGINT" || event === "SIGTERM") && typeof listener === "function") { + process.off(event, listener); + } + } + process.exitCode = previousExitCode; + processOnceSpy.mockRestore(); + } + }); + it("routes invoke input, cancellation, and connection close to the runtime", async () => { mocks.useFakeRuntime = true; await expect(runNodeHost({ gatewayHost: "127.0.0.1", gatewayPort: 18789 })).rejects.toThrow( diff --git a/src/node-host/runner.ts b/src/node-host/runner.ts index 98f79ef0b920..13b17c34c1a1 100644 --- a/src/node-host/runner.ts +++ b/src/node-host/runner.ts @@ -7,16 +7,13 @@ import { import { ConnectErrorDetailCodes } from "../../packages/gateway-protocol/src/connect-error-details.js"; import { getRuntimeConfig, type OpenClawConfig } from "../config/config.js"; import { startGatewayClientWhenEventLoopReady } from "../gateway/client-start-readiness.js"; -import { - GatewayClient, - GatewayClientRequestError, - type GatewayReconnectPausedInfo, -} from "../gateway/client.js"; +import { GatewayClientRequestError, type GatewayReconnectPausedInfo } from "../gateway/client.js"; import { resolveGatewayCredentialsWithSecretInputs } from "../gateway/credentials-secret-inputs.js"; import { loadOrCreateDeviceIdentity } from "../infra/device-identity.js"; import { getMachineDisplayName } from "../infra/machine-name.js"; import { VERSION } from "../version.js"; import { configureNodeHost, type NodeHostGatewayConfig } from "./config.js"; +import { createNodeHostGatewayCandidateConnection } from "./gateway-candidate-connection.js"; import { coerceNodeInvokeCancelPayload, coerceNodeInvokeInputPayload, @@ -30,6 +27,9 @@ type NodeHostRunOptions = { gatewayPort: number; gatewayTls?: boolean; gatewayTlsFingerprint?: string; + gatewayCandidates?: NodeHostGatewayConfig[]; + gatewayBootstrapToken?: string; + preferGatewayBootstrapToken?: boolean; /** Optional WebSocket context path (e.g. "/openclaw-gw"). */ gatewayContextPath?: string; nodeId?: string; @@ -220,6 +220,7 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise { const nodeId = config.nodeId; const displayName = config.displayName ?? fallbackDisplayName; const gateway = config.gateway ?? plannedGateway; + const gatewayCandidates = opts.gatewayCandidates?.length ? opts.gatewayCandidates : [gateway]; const cfg = getRuntimeConfig(); const preparedRuntime = await prepareNodeHostRuntime({ @@ -228,22 +229,13 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise { enableAgentRuns: true, installedAppsSharingEnabled: config.installedAppsSharing, }); - const { token, password } = await resolveNodeHostGatewayCredentials({ - config: cfg, - env: process.env, - }); + const { token, password } = opts.preferGatewayBootstrapToken + ? {} + : await resolveNodeHostGatewayCredentials({ + config: cfg, + env: process.env, + }); - const host = gateway.host ?? "127.0.0.1"; - const urlHost = - host.includes(":") && !(host.startsWith("[") && host.endsWith("]")) ? `[${host}]` : host; - const port = gateway.port ?? 18789; - const scheme = gateway.tls ? "wss" : "ws"; - const contextPath = gateway.contextPath - ? gateway.contextPath.startsWith("/") - ? gateway.contextPath - : `/${gateway.contextPath}` - : ""; - const url = `${scheme}://${urlHost}:${port}${contextPath}`; let inventory: NodeHostInventory = preparedRuntime.initialInventory; let gatewayHelloReceived = false; let gatewayConnectionGeneration = 0; @@ -451,27 +443,42 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise { ); }; - const client = new GatewayClient({ - url, - token: token || undefined, - password: password || undefined, - instanceId: nodeId, - clientName: GATEWAY_CLIENT_NAMES.NODE_HOST, - clientDisplayName: displayName, - clientVersion: VERSION, - platform: resolveNodeHostGatewayPlatform(process.platform), - deviceFamily: resolveNodeHostGatewayDeviceFamily(process.platform), - mode: GATEWAY_CLIENT_MODES.NODE, - role: "node", - scopes: [], - // Pair the built-in MCP command family up front. Server inventory is - // restart-scoped availability, not a capability upgrade requiring re-pairing. - caps: preparedRuntime.manifest.caps, - commands: preparedRuntime.manifest.commands, - pathEnv: preparedRuntime.manifest.pathEnv, - permissions: undefined, - deviceIdentity: loadOrCreateDeviceIdentity(), - tlsFingerprint: gateway.tlsFingerprint, + const persistWinningGateway = (winningGateway: NodeHostGatewayConfig) => { + void configureNodeHost({ + nodeId, + displayName, + fallbackDisplayName, + gateway: winningGateway, + installedAppsSharing: config.installedAppsSharing, + }).catch((error: unknown) => { + writeStderrLine(`node host gateway endpoint persistence failed: ${String(error)}`); + }); + }; + + const client = createNodeHostGatewayCandidateConnection({ + candidates: gatewayCandidates, + clientOptions: { + token: token || undefined, + bootstrapToken: opts.gatewayBootstrapToken, + preferBootstrapToken: opts.preferGatewayBootstrapToken, + password: password || undefined, + instanceId: nodeId, + clientName: GATEWAY_CLIENT_NAMES.NODE_HOST, + clientDisplayName: displayName, + clientVersion: VERSION, + platform: resolveNodeHostGatewayPlatform(process.platform), + deviceFamily: resolveNodeHostGatewayDeviceFamily(process.platform), + mode: GATEWAY_CLIENT_MODES.NODE, + role: "node", + scopes: [], + // Pair the built-in MCP command family up front. Server inventory is + // restart-scoped availability, not a capability upgrade requiring re-pairing. + caps: preparedRuntime.manifest.caps, + commands: preparedRuntime.manifest.commands, + pathEnv: preparedRuntime.manifest.pathEnv, + permissions: undefined, + deviceIdentity: loadOrCreateDeviceIdentity(), + }, onEvent: (evt) => { if (evt.event === "node.invoke.cancel") { const payload = coerceNodeInvokeCancelPayload(evt.payload); @@ -491,12 +498,11 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise { return; } const payload = coerceNodeInvokePayload(evt.payload); - if (!payload) { - return; + if (payload) { + void activeRuntime.invoke(payload); } - void activeRuntime.invoke(payload); }, - onHelloOk: (hello) => { + onHelloOk: (hello, url) => { writeStderrLine(`node host gateway connected: ${url}`); gatewayConnectionGeneration += 1; gatewayHelloReceived = true; @@ -505,9 +511,9 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise { optionalPublicationStates = new Map(); publishInventory(); }, - onConnectError: (err) => { + onConnectError: (error) => { // keep retrying (handled by GatewayClient) - writeStderrLine(`node host gateway connect failed: ${err.message}`); + writeStderrLine(`node host gateway connect failed: ${error.message}`); }, onReconnectPaused: (info) => { handleNodeHostReconnectPaused(info, { @@ -524,6 +530,7 @@ export async function runNodeHost(opts: NodeHostRunOptions): Promise { activeRuntime.cancelAll(); writeStderrLine(`node host gateway closed (${code}): ${reason}`); }, + onWinningCandidate: persistWinningGateway, }); const activeRuntime = preparedRuntime.start({ client, diff --git a/src/pairing/setup-code.test.ts b/src/pairing/setup-code.test.ts index 873e1ab12b2f..4a305bc5d2bc 100644 --- a/src/pairing/setup-code.test.ts +++ b/src/pairing/setup-code.test.ts @@ -14,11 +14,41 @@ vi.mock("../infra/device-bootstrap.js", () => ({ })), })); -const { encodePairingSetupCode, resolvePairingSetupFromConfig } = await import("./setup-code.js"); +const { decodePairingSetupCode, encodePairingSetupCode, resolvePairingSetupFromConfig } = + await import("./setup-code.js"); const { issueDeviceBootstrapToken: issueDeviceBootstrapTokenMock } = await import("../infra/device-bootstrap.js"); describe("pairing setup code", () => { + it("round-trips bare and wrapped setup codes without normalizing payload case", () => { + const payload = { + url: "wss://gateway.example:8443/openclaw-gw", + bootstrapToken: "Bootstrap-AbC123", + tlsFingerprint: "sha256:AA:BB", + expiresAtMs: 20_000, + }; + const setupCode = encodePairingSetupCode(payload); + expect(setupCode).toMatch(/[A-Z]/u); + + expect(decodePairingSetupCode(setupCode, { nowMs: 10_000 })).toEqual(payload); + expect(decodePairingSetupCode(`oc-pair://${setupCode}`, { nowMs: 10_000 })).toEqual(payload); + }); + + it("rejects garbage and expired shipped payload shapes", () => { + expect(() => decodePairingSetupCode("not-json")).toThrow("Invalid pairing setup"); + const expired = encodePairingSetupCode({ + url: "wss://gateway.example", + bootstrapToken: "bootstrap-123", + expiresAtMs: 10_000, + }); + expect(() => decodePairingSetupCode(expired, { nowMs: 10_000 })).toThrow("expired"); + }); + + it("accepts older payloads without a TLS fingerprint or expiry", () => { + const payload = { url: "wss://gateway.example", bootstrapToken: "bootstrap-123" }; + expect(decodePairingSetupCode(encodePairingSetupCode(payload))).toEqual(payload); + }); + type ResolvedSetup = Awaited>; type ResolveSetupConfig = Parameters[0]; type ResolveSetupOptions = Parameters[1]; @@ -286,6 +316,20 @@ describe("pairing setup code", () => { }); }); + it("preserves context paths in fully qualified setup urls", async () => { + await expectResolvedSetupSuccessCase({ + config: createCustomGatewayConfig({ mode: "token", token: "tok_123" }), + options: { + publicUrl: "wss://gateway.example.test:18789/openclaw-gw", + }, + expected: { + authLabel: "token", + url: "wss://gateway.example.test:18789/openclaw-gw", + urlSource: "plugins.entries.device-pair.config.publicUrl", + }, + }); + }); + it("issues a node-only bootstrap profile for companion setup", async () => { await expectResolvedSetupSuccessCase({ config: createCustomGatewayConfig({ mode: "token", token: "tok_123" }), @@ -938,4 +982,35 @@ describe("pairing setup code", () => { expectedError: "Service MagicDNS could not be derived", }); }); + + it("pins the prepared leaf only for a direct TLS gateway URL", async () => { + const config = createCustomGatewayConfig({ mode: "token", token: "tok_123" }); + config.gateway = { ...config.gateway, tls: { enabled: true } }; + const direct = await resolvePairingSetupFromConfig(config, { + localTlsFingerprint: "sha256:direct-leaf", + }); + const proxied = await resolvePairingSetupFromConfig(config, { + publicUrl: "wss://proxy.example", + localTlsFingerprint: "sha256:direct-leaf", + }); + + expect(direct.ok && direct.payload.tlsFingerprint).toBe("sha256:direct-leaf"); + expect(proxied.ok && proxied.payload.tlsFingerprint).toBeUndefined(); + }); + + it("omits a configured remote TLS pin from a cleartext setup URL", async () => { + const config = createCustomGatewayConfig({ mode: "token", token: "tok_123" }); + config.gateway = { + ...config.gateway, + remote: { + url: "ws://127.0.0.1:18789", + tlsFingerprint: "sha256:stale-remote-leaf", + }, + }; + + const resolved = await resolvePairingSetupFromConfig(config, { preferRemoteUrl: true }); + + expect(resolved.ok).toBe(true); + expect(resolved.ok && resolved.payload.tlsFingerprint).toBeUndefined(); + }); }); diff --git a/src/pairing/setup-code.ts b/src/pairing/setup-code.ts index b99c638aa057..6725fbfcf54d 100644 --- a/src/pairing/setup-code.ts +++ b/src/pairing/setup-code.ts @@ -8,6 +8,7 @@ import { isRfc1918Ipv4Address, parseCanonicalIpAddress, } from "@openclaw/net-policy/ip"; +import { isRecord } from "@openclaw/normalization-core/record-coerce"; import { normalizeLowercaseStringOrEmpty, normalizeOptionalString, @@ -42,6 +43,8 @@ type PairingSetupPayload = { url: string; urls?: string[]; bootstrapToken: string; + expiresAtMs?: number; + tlsFingerprint?: string; }; type PairingSetupAccess = "full" | "limited" | "node"; @@ -68,6 +71,8 @@ type ResolvePairingSetupOptions = { pairingBaseDir?: string; runCommandWithTimeout?: PairingSetupCommandRunner; networkInterfaces?: () => ReturnType; + localTlsFingerprint?: string; + loadLocalTlsFingerprint?: () => Promise; }; type PairingSetupResolution = @@ -78,6 +83,7 @@ type PairingSetupResolution = urlSource: string; access: PairingSetupAccess; accessDowngraded: boolean; + expiresAtMs: number; } | { ok: false; @@ -239,7 +245,8 @@ function parseNormalizedGatewayUrl(raw: string): string | null { return null; } const port = parsed.port ? `:${parsed.port}` : ""; - return `${resolvedScheme}://${host}${port}`; + const contextPath = parsed.pathname === "/" ? "" : parsed.pathname; + return `${resolvedScheme}://${host}${port}${contextPath}`; } catch { return null; } @@ -409,6 +416,79 @@ export function encodePairingSetupCode(payload: PairingSetupPayload): string { return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, ""); } +const PAIRING_SETUP_URL_PREFIX = "oc-pair://"; +const PAIRING_SETUP_CODE_RE = /^[A-Za-z0-9_-]+$/u; + +/** Decode the current setup payload plus additive fields emitted by older pairing surfaces. */ +export function decodePairingSetupCode( + input: string, + options: { nowMs?: number } = {}, +): PairingSetupPayload { + const trimmed = input.trim(); + const setupCode = trimmed.toLowerCase().startsWith(PAIRING_SETUP_URL_PREFIX) + ? trimmed.slice(PAIRING_SETUP_URL_PREFIX.length) + : trimmed; + if (!setupCode || !PAIRING_SETUP_CODE_RE.test(setupCode)) { + throw new Error("Invalid pairing setup code or URL."); + } + + let decoded: unknown; + try { + decoded = JSON.parse(Buffer.from(setupCode, "base64url").toString("utf8")); + } catch { + throw new Error("Invalid pairing setup code or URL."); + } + if (!isRecord(decoded)) { + throw new Error("Invalid pairing setup payload."); + } + + const url = normalizeOptionalString(decoded.url); + const bootstrapToken = normalizeOptionalString(decoded.bootstrapToken); + if (!url || !bootstrapToken || normalizeUrl(url, "ws") !== url) { + throw new Error("Invalid pairing setup payload."); + } + + let urls: string[] | undefined; + if (decoded.urls !== undefined) { + if ( + !Array.isArray(decoded.urls) || + decoded.urls.length === 0 || + decoded.urls.length > PAIRING_SETUP_MAX_URLS || + decoded.urls.some( + (candidate) => typeof candidate !== "string" || normalizeUrl(candidate, "ws") !== candidate, + ) + ) { + throw new Error("Invalid pairing setup payload."); + } + urls = decoded.urls; + } + + let expiresAtMs: number | undefined; + if (decoded.expiresAtMs !== undefined) { + const candidate = decoded.expiresAtMs; + if (typeof candidate !== "number" || !Number.isSafeInteger(candidate) || candidate < 0) { + throw new Error("Invalid pairing setup payload."); + } + expiresAtMs = candidate; + if (candidate <= (options.nowMs ?? Date.now())) { + throw new Error("Pairing setup code has expired."); + } + } + + const tlsFingerprint = normalizeOptionalString(decoded.tlsFingerprint); + if (decoded.tlsFingerprint !== undefined && !tlsFingerprint) { + throw new Error("Invalid pairing setup payload."); + } + + return { + url, + ...(urls ? { urls } : {}), + bootstrapToken, + ...(expiresAtMs !== undefined ? { expiresAtMs } : {}), + ...(tlsFingerprint ? { tlsFingerprint } : {}), + }; +} + export async function resolvePairingSetupFromConfig( cfg: OpenClawConfig, options: ResolvePairingSetupOptions = {}, @@ -476,18 +556,28 @@ export async function resolvePairingSetupFromConfig( ? PAIRING_SETUP_BOOTSTRAP_PROFILE : requestedBootstrapProfile; + const issuedBootstrap = await issueDeviceBootstrapToken({ + baseDir: options.pairingBaseDir, + profile: issuedBootstrapProfile, + }); + const directGatewayTlsFingerprint = + urlResult.url.startsWith("wss://") && urlResult.source?.startsWith("gateway.bind=") + ? (normalizeOptionalString(options.localTlsFingerprint) ?? + (await options.loadLocalTlsFingerprint?.())) + : urlResult.url.startsWith("wss://") && urlResult.source === "gateway.remote.url" + ? normalizeOptionalString(cfgForAuth.gateway?.remote?.tlsFingerprint) + : undefined; + return { ok: true, payload: { url: urlResult.url, ...(uniqueUrls.length > 1 ? { urls: uniqueUrls } : {}), - bootstrapToken: ( - await issueDeviceBootstrapToken({ - baseDir: options.pairingBaseDir, - profile: issuedBootstrapProfile, - }) - ).token, + bootstrapToken: issuedBootstrap.token, + expiresAtMs: issuedBootstrap.expiresAtMs, + ...(directGatewayTlsFingerprint ? { tlsFingerprint: directGatewayTlsFingerprint } : {}), }, + expiresAtMs: issuedBootstrap.expiresAtMs, authLabel: authLabel.label, urlSource: urlResult.source ?? "unknown", access: resolvePairingSetupAccess(issuedBootstrapProfile), diff --git a/ui/src/app/app-host-pairing-access.test.ts b/ui/src/app/app-host-pairing-access.test.ts index df6fe250dd3c..3c4db1d3faa1 100644 --- a/ui/src/app/app-host-pairing-access.test.ts +++ b/ui/src/app/app-host-pairing-access.test.ts @@ -3,6 +3,7 @@ import { render, type TemplateResult } from "lit"; import { afterEach, describe, expect, it, vi } from "vitest"; import type { GatewayBrowserClient } from "../api/gateway.ts"; +import { OpenClawDevicePairSetup } from "../pages/devices/view-pairing.ts"; import type { ApplicationRuntime } from "./bootstrap.ts"; import type { ApplicationContext, ApplicationGatewaySnapshot } from "./context.ts"; import "./app-host.ts"; @@ -23,7 +24,12 @@ function createPairingShell(params: { auth: PairingAuth | null; connected?: boolean; setupCode?: string; + expiresAtMs?: number; + approvalNowMs?: number; }) { + if (!customElements.get("openclaw-device-pair-setup")) { + customElements.define("openclaw-device-pair-setup", OpenClawDevicePairSetup); + } const snapshot: ApplicationGatewaySnapshot = { client: { request: vi.fn(async () => ({})) } as unknown as GatewayBrowserClient, phase: params.connected === false ? "stopped" : "connected", @@ -36,6 +42,30 @@ function createPairingShell(params: { lastErrorCode: null, }; const openDevicePairSetup = vi.fn(async () => undefined); + const overlaySnapshot = { + approvalQueue: [], + approvalErrors: new Map(), + approvalNowMs: params.approvalNowMs ?? 0, + approvalBusy: false, + devicePairSetupOpen: Boolean(params.setupCode), + devicePairSetupLoading: false, + devicePairSetupError: null, + devicePairSetup: params.setupCode + ? { + setupCode: params.setupCode, + gatewayUrl: "wss://gateway.example.test", + auth: "token", + urlSource: "test", + ...(params.expiresAtMs === undefined ? {} : { expiresAtMs: params.expiresAtMs }), + } + : null, + devicePairSetupAccess: "full", + devicePairPendingCount: 0, + updateAvailable: null, + updateRunning: false, + updateStatusBanner: null, + controlUiRefreshRequired: false, + }; const context = { basePath: "", gateway: { @@ -46,29 +76,7 @@ function createPairingShell(params: { snapshot: { navCollapsed: false, navWidth: 258, sidebarEntries: [], pinnedAgentIds: [] }, }, overlays: { - snapshot: { - approvalQueue: [], - approvalErrors: new Map(), - approvalNowMs: 0, - approvalBusy: false, - devicePairSetupOpen: Boolean(params.setupCode), - devicePairSetupLoading: false, - devicePairSetupError: null, - devicePairSetup: params.setupCode - ? { - setupCode: params.setupCode, - gatewayUrl: "wss://gateway.example.test", - auth: "token", - urlSource: "test", - } - : null, - devicePairSetupAccess: "full", - devicePairPendingCount: 0, - updateAvailable: null, - updateRunning: false, - updateStatusBanner: null, - controlUiRefreshRequired: false, - }, + snapshot: overlaySnapshot, openDevicePairSetup, }, config: { current: {} }, @@ -81,7 +89,13 @@ function createPairingShell(params: { theme: { mode: "system" }, } as unknown as ApplicationContext; const shell = document.createElement("openclaw-app-shell") as PairingShell; - shell.runtime = { context, router: {} } as ApplicationRuntime; + shell.runtime = { + context, + router: { + getState: () => ({ status: "idle", matches: [], pendingMatches: [] }), + subscribeSelector: () => () => undefined, + }, + } as unknown as ApplicationRuntime; const container = document.createElement("div"); const renderSidebar = () => { @@ -93,11 +107,13 @@ function createPairingShell(params: { return sidebar; }; - return { snapshot, openDevicePairSetup, renderSidebar, container }; + return { snapshot, overlaySnapshot, openDevicePairSetup, renderSidebar, container }; } -afterEach(() => { +afterEach(async () => { + vi.useRealTimers(); document.body.replaceChildren(); + await Promise.resolve(); vi.unstubAllGlobals(); vi.restoreAllMocks(); Reflect.deleteProperty(document, "execCommand"); @@ -161,12 +177,12 @@ describe("application shell pairing access", () => { auth: { role: "operator", scopes: ["operator.pairing"] }, setupCode: "pair-mobile-secret", }); + document.body.append(container); renderSidebar(); - const pairing = container.querySelector(".device-pair-setup"); - if (!pairing) { - throw new Error("Expected the application shell to render its mobile pairing dialog"); - } - document.body.append(pairing); + await vi.waitFor(() => + expect(container.querySelector(".device-pair-setup")).not.toBeNull(), + ); + const pairing = container.querySelector(".device-pair-setup")!; const button = pairing.querySelector(".device-pair-setup__actions button"); button?.click(); @@ -186,4 +202,31 @@ describe("application shell pairing access", () => { expect(button?.textContent?.trim()).toBe("Copy setup code"); expect(button?.getAttribute("aria-label")).toBe("Copy setup code"); }); + + it("expires a node setup link from the pairing clock, independently of approvals", async () => { + const now = vi.spyOn(Date, "now").mockReturnValue(4_000); + const { overlaySnapshot, container, renderSidebar } = createPairingShell({ + auth: { role: "operator", scopes: ["operator.pairing"] }, + setupCode: "pair-node-secret", + expiresAtMs: 5_000, + approvalNowMs: 50_000, + }); + document.body.append(container); + overlaySnapshot.devicePairSetupAccess = "node"; + + renderSidebar(); + await vi.waitFor(() => + expect(container.querySelector('[role="timer"]')?.textContent).toContain("0:01"), + ); + expect(container.querySelector(".device-pair-setup__command code")).not.toBeNull(); + + now.mockReturnValue(5_000); + renderSidebar(); + await vi.waitFor(() => + expect(container.querySelector('[role="timer"]')?.textContent?.toLowerCase()).toContain( + "expired", + ), + ); + expect(container.querySelector(".device-pair-setup__command code")).toBeNull(); + }); }); diff --git a/ui/src/app/app-host.ts b/ui/src/app/app-host.ts index fce48efb0114..e38a624153e7 100644 --- a/ui/src/app/app-host.ts +++ b/ui/src/app/app-host.ts @@ -65,6 +65,7 @@ import { COMMAND_PALETTE_ELEMENT, CUSTODIAN_PANEL_ELEMENT, DESKTOP_PANEL_ELEMENT, + DEVICE_PAIR_SETUP_ELEMENT, EXEC_APPROVAL_ELEMENT, preloadOptionalElement, TERMINAL_PANEL_ELEMENT, @@ -135,6 +136,7 @@ class OpenClawShell readonly browserPanelElement = BROWSER_PANEL_ELEMENT; readonly desktopPanelElement = DESKTOP_PANEL_ELEMENT; readonly custodianPanelElement = CUSTODIAN_PANEL_ELEMENT; + readonly devicePairSetupElement = DEVICE_PAIR_SETUP_ELEMENT; readonly execApprovalElement = EXEC_APPROVAL_ELEMENT; @query("openclaw-command-palette") commandPalette: CommandPaletteElement | undefined; @query("openclaw-exec-approval") @@ -545,6 +547,9 @@ class OpenClawShell if ((context.overlays?.snapshot.approvalQueue.length ?? 0) > 0) { preloadOptionalElement(this, this.execApprovalElement); } + if (context.overlays?.snapshot.devicePairSetupOpen) { + preloadOptionalElement(this, this.devicePairSetupElement); + } const navState = { collapsed: this.nativeNavCollapsed(), width: context.navigation.snapshot.navWidth, diff --git a/ui/src/app/app-shell-view.ts b/ui/src/app/app-shell-view.ts index 4ccee15ef81e..45a17945dde4 100644 --- a/ui/src/app/app-shell-view.ts +++ b/ui/src/app/app-shell-view.ts @@ -16,7 +16,6 @@ import { findUiSessionRow } from "../lib/sessions/route-navigation.ts"; import { normalizeAgentId } from "../lib/sessions/session-key.ts"; import { isTerminalAvailable } from "../lib/terminal-availability.ts"; import { findSettingsSearchBlocks } from "../pages/config/settings-search.ts"; -import { renderDevicePairSetup } from "../pages/devices/view-pairing.ts"; import type { NewSessionTarget } from "../pages/new-session/location.ts"; import { pluginTabKey, pluginTabRefFromSearch } from "../pages/plugin/route.ts"; import type { ShellRouteState } from "./app-host-route-state.ts"; @@ -54,6 +53,7 @@ export interface ShellViewHost { readonly commandPaletteElement: OptionalCustomElement; readonly custodianMinimizeRequestId: number; readonly desktopNavigationExpanded: boolean; + readonly devicePairSetupElement: OptionalCustomElement; readonly execApprovalElement: OptionalCustomElement; readonly nativeHistoryState: NativeHistoryState; readonly navDrawerOpen: boolean; @@ -544,25 +544,32 @@ export function renderApplicationShell(host: ShellViewHost) { }} >` : nothing} - ${renderDevicePairSetup({ - open: overlaySnapshot.devicePairSetupOpen, - loading: overlaySnapshot.devicePairSetupLoading, - error: overlaySnapshot.devicePairSetupError, - setup: overlaySnapshot.devicePairSetup, - access: overlaySnapshot.devicePairSetupAccess, - pendingCount: overlaySnapshot.devicePairPendingCount, - onRefresh: () => void context.overlays.refreshDevicePairSetup(), - onAccessChange: (access) => void context.overlays.setDevicePairSetupAccess(access), - onClose: () => context.overlays.closeDevicePairSetup(), - onManageDevices: () => { - context.overlays.closeDevicePairSetup(); - host.navigate("devices"); - }, - onGetApps: () => { - context.overlays.closeDevicePairSetup(); - host.navigate("apps"); - }, - })} + ${isOptionalElementDefined(host.devicePairSetupElement) + ? html` void context.overlays.refreshDevicePairSetup(), + onAccessChange: ( + access: Parameters[0], + ) => void context.overlays.setDevicePairSetupAccess(access), + onClose: () => context.overlays.closeDevicePairSetup(), + onManageDevices: () => { + context.overlays.closeDevicePairSetup(); + host.navigate("devices"); + }, + onGetApps: () => { + context.overlays.closeDevicePairSetup(); + host.navigate("apps"); + }, + }} + >` + : nothing} ${onboarding && activeRoute !== "custodian" ? html` import("../components/exec-approval.ts"), } satisfies OptionalCustomElement; +const DEVICE_PAIR_SETUP_TAG = "openclaw-device-pair-setup"; + +export const DEVICE_PAIR_SETUP_ELEMENT = { + tagName: DEVICE_PAIR_SETUP_TAG, + label: DEVICE_PAIR_SETUP_TAG, + loadModule: () => import("../pages/devices/view-pairing.ts"), +} satisfies OptionalCustomElement; + const hostElementLoads = new WeakMap>>(); export function isOptionalElementDefined(element: OptionalCustomElement): boolean { diff --git a/ui/src/app/overlays-types.ts b/ui/src/app/overlays-types.ts new file mode 100644 index 000000000000..395f5a945f65 --- /dev/null +++ b/ui/src/app/overlays-types.ts @@ -0,0 +1,41 @@ +import type { UpdateAvailable, UpdateScheduleState } from "../api/types.ts"; +import type { DevicePairSetup, DevicePairSetupAccess } from "../lib/device-pair-setup.ts"; +import type { DeviceAuthMigrationSnapshot } from "./device-auth-migration.ts"; +import type { ExecApprovalDecision, ExecApprovalRequest } from "./exec-approval.ts"; +import type { ApplicationStatusBanner } from "./update-overlay-helpers.ts"; + +export type ApplicationOverlaySnapshot = { + updateAvailable: UpdateAvailable | null; + updateSchedule: UpdateScheduleState | null; + heldUpdateCampaignId: string | null; + updateRunning: boolean; + updateReconciliationPending: boolean; + updateStatusBanner: ApplicationStatusBanner | null; + controlUiRefreshRequired: boolean; + approvalQueue: readonly ExecApprovalRequest[]; + approvalBusy: boolean; + approvalErrors: ReadonlyMap; + approvalNowMs: number; + devicePairSetupOpen: boolean; + devicePairSetupLoading: boolean; + devicePairSetupError: string | null; + devicePairSetup: DevicePairSetup | null; + devicePairSetupAccess: DevicePairSetupAccess; + devicePairPendingCount: number; + deviceAuthMigration: DeviceAuthMigrationSnapshot; +}; + +export type ApplicationOverlays = { + readonly snapshot: ApplicationOverlaySnapshot; + subscribe: (listener: (snapshot: ApplicationOverlaySnapshot) => void) => () => void; + refreshUpdateStatus: () => Promise; + runUpdate: () => Promise; + holdUpdate: () => Promise; + decideApproval: (decision: ExecApprovalDecision, approvalId?: string) => Promise; + openDevicePairSetup: () => Promise; + refreshDevicePairSetup: () => Promise; + setDevicePairSetupAccess: (access: DevicePairSetupAccess) => Promise; + closeDevicePairSetup: () => void; + secureThisBrowser: () => Promise; + dispose: () => void; +}; diff --git a/ui/src/app/overlays.ts b/ui/src/app/overlays.ts index 2237609ba964..8630833379a4 100644 --- a/ui/src/app/overlays.ts +++ b/ui/src/app/overlays.ts @@ -3,7 +3,7 @@ import { type GatewayUpdateAvailableEventPayload, } from "../../../src/gateway/events.js"; import type { GatewayEventFrame } from "../api/gateway.ts"; -import type { UpdateAvailable, UpdateHoldResult, UpdateScheduleState } from "../api/types.ts"; +import type { UpdateHoldResult, UpdateScheduleState } from "../api/types.ts"; import { controlUiVersionDiffersFrom } from "../build-info.ts"; import { t } from "../i18n/index.ts"; import { @@ -13,8 +13,7 @@ import { readDevicePairSetupSnapshot, refreshDevicePairSetup as refreshDevicePairSetupState, setDevicePairSetupAccess as setPairAccess, - type DevicePairSetup, - type DevicePairSetupAccess, + syncDevicePairSetupCountdown, } from "../lib/device-pair-setup.ts"; import { createDeviceAuthMigrationLoader, @@ -28,12 +27,12 @@ import { parseApprovalRequestedEvent, parseExecApprovalResolved, resolveApprovalRequest, - type ExecApprovalDecision, type ExecApprovalPromptState, - type ExecApprovalRequest, } from "./exec-approval.ts"; import type { ApplicationGateway } from "./gateway.ts"; import { readGatewayOperatorAccess } from "./operator-access.ts"; +import type { ApplicationOverlays, ApplicationOverlaySnapshot } from "./overlays-types.ts"; +export type { ApplicationOverlays } from "./overlays-types.ts"; import { createOverlayApprovalRefresher, createOverlayPairingPendingCount, @@ -65,42 +64,6 @@ import { announceVerifiedUpdateInstall, } from "./update-success-notice.ts"; -type ApplicationOverlaySnapshot = { - updateAvailable: UpdateAvailable | null; - updateSchedule: UpdateScheduleState | null; - heldUpdateCampaignId: string | null; - updateRunning: boolean; - updateReconciliationPending: boolean; - updateStatusBanner: ApplicationStatusBanner | null; - controlUiRefreshRequired: boolean; - approvalQueue: readonly ExecApprovalRequest[]; - approvalBusy: boolean; - approvalErrors: ReadonlyMap; - approvalNowMs: number; - devicePairSetupOpen: boolean; - devicePairSetupLoading: boolean; - devicePairSetupError: string | null; - devicePairSetup: DevicePairSetup | null; - devicePairSetupAccess: DevicePairSetupAccess; - devicePairPendingCount: number; - deviceAuthMigration: import("./device-auth-migration.ts").DeviceAuthMigrationSnapshot; -}; - -export type ApplicationOverlays = { - readonly snapshot: ApplicationOverlaySnapshot; - subscribe: (listener: (snapshot: ApplicationOverlaySnapshot) => void) => () => void; - refreshUpdateStatus: () => Promise; - runUpdate: () => Promise; - holdUpdate: () => Promise; - decideApproval: (decision: ExecApprovalDecision, approvalId?: string) => Promise; - openDevicePairSetup: () => Promise; - refreshDevicePairSetup: () => Promise; - setDevicePairSetupAccess: (access: DevicePairSetupAccess) => Promise; - closeDevicePairSetup: () => void; - secureThisBrowser: () => Promise; - dispose: () => void; -}; - function isGatewayEvent(value: unknown): value is GatewayEventFrame { return Boolean(value && typeof value === "object" && "event" in value); } @@ -192,6 +155,7 @@ export function createApplicationOverlays( publish(); await operation; if (!disposed) { + syncDevicePairSetupCountdown(devicePairSetupState, publish); publish(); } }; diff --git a/ui/src/app/update-overlay-helpers.ts b/ui/src/app/update-overlay-helpers.ts index 7718a8616ddf..80bf81112cc2 100644 --- a/ui/src/app/update-overlay-helpers.ts +++ b/ui/src/app/update-overlay-helpers.ts @@ -1,6 +1,7 @@ import type { GatewayBrowserClient, GatewayHelloOk } from "../api/gateway.ts"; import type { UpdateAvailable, UpdateScheduleState } from "../api/types.ts"; import { t } from "../i18n/index.ts"; +import { formatCountdown } from "../lib/format.ts"; import { readUpdateAvailableValue, readUpdateScheduleValue } from "./update-schedule-dto.ts"; export type ApplicationStatusBanner = { @@ -453,12 +454,6 @@ export function projectUpdateStatusResponse( }; } -function formatUpdateCountdown(deadlineMs: number, nowMs = Date.now()): string { - const totalSeconds = Math.max(0, Math.ceil((deadlineMs - nowMs) / 1_000)); - const minutes = Math.floor(totalSeconds / 60); - return `${minutes}:${String(totalSeconds % 60).padStart(2, "0")}`; -} - export function formatUpdateCampaignLabel( schedule: UpdateScheduleState | null | undefined, nowMs = Date.now(), @@ -469,7 +464,7 @@ export function formatUpdateCampaignLabel( } if (campaign.holdUntilMs !== undefined && campaign.holdUntilMs > nowMs) { return t("updates.campaign.held", { - time: formatUpdateCountdown(campaign.holdUntilMs, nowMs), + time: formatCountdown(campaign.holdUntilMs, nowMs), }); } if (campaign.state === "applying") { @@ -477,11 +472,11 @@ export function formatUpdateCampaignLabel( } if (campaign.state === "waiting-for-idle") { return t("updates.campaign.waitingForIdle", { - time: formatUpdateCountdown(campaign.forceAtMs, nowMs), + time: formatCountdown(campaign.forceAtMs, nowMs), }); } return t("updates.campaign.countdown", { - time: formatUpdateCountdown(campaign.applyAtMs ?? campaign.forceAtMs, nowMs), + time: formatCountdown(campaign.applyAtMs ?? campaign.forceAtMs, nowMs), }); } diff --git a/ui/src/components/exec-approval-card.ts b/ui/src/components/exec-approval-card.ts index d2409f305b8c..09401ad6539a 100644 --- a/ui/src/components/exec-approval-card.ts +++ b/ui/src/components/exec-approval-card.ts @@ -7,6 +7,7 @@ import type { ExecApprovalRequestPayload, } from "../app/exec-approval.ts"; import { t } from "../i18n/index.ts"; +import { formatCountdown } from "../lib/format.ts"; const DEFAULT_EXEC_APPROVAL_DECISIONS = [ "allow-once", @@ -24,14 +25,9 @@ type ExecApprovalCardProps = { onDecision: (approvalId: string, decision: ExecApprovalDecision) => void | Promise; }; -export function formatApprovalCountdown(expiresAtMs: number, nowMs: number): string { - const totalSeconds = Math.max(0, Math.ceil((expiresAtMs - nowMs) / 1_000)); - return `${String(Math.floor(totalSeconds / 60)).padStart(2, "0")}:${String(totalSeconds % 60).padStart(2, "0")}`; -} - export function approvalRemainingLabel(expiresAtMs: number, nowMs: number): string { return expiresAtMs > nowMs - ? t("execApproval.expiresIn", { time: formatApprovalCountdown(expiresAtMs, nowMs) }) + ? t("execApproval.expiresIn", { time: formatCountdown(expiresAtMs, nowMs, true) }) : t("execApproval.expired"); } diff --git a/ui/src/components/exec-approval.ts b/ui/src/components/exec-approval.ts index 4ca82da224ec..04fab4422544 100644 --- a/ui/src/components/exec-approval.ts +++ b/ui/src/components/exec-approval.ts @@ -5,12 +5,12 @@ import { property, query, state } from "lit/decorators.js"; import { modalApprovalQueue } from "../app/approval-presentation.ts"; import type { ExecApprovalDecision, ExecApprovalRequest } from "../app/exec-approval.ts"; import { t } from "../i18n/index.ts"; +import { formatCountdown } from "../lib/format.ts"; import { resolveAsciiShortcutKey } from "../lib/keyboard-shortcuts.ts"; import { OpenClawLightDomContentsElement } from "../lit/openclaw-element.ts"; import { approvalRemainingLabel, approvalTitle, - formatApprovalCountdown, renderExecApprovalCard, resolveApprovalDecisions, } from "./exec-approval-card.ts"; @@ -47,7 +47,7 @@ function renderApprovalQueueList(params: { ${others.map((entry) => { const command = compactCommand(entry.request.command); const agent = entry.request.agentId?.trim() || "—"; - const countdown = formatApprovalCountdown(entry.expiresAtMs, params.nowMs); + const countdown = formatCountdown(entry.expiresAtMs, params.nowMs, true); return html` -

+ ${isNodeSetup + ? nothing + : html`

+ ${t("devices.pairing.noApp")} + +

`} + ${isNodeSetup + ? nothing + : html``}