chore: sync fork main with upstream OpenHands/OpenHands

.github/scripts/check_pr_description.py

@@ -57,6 +57,8 @@
     ".sass",
     ".less",
 )
+# Docs carry no visual state, so a screenshot can't evidence a change to them.
+DOCUMENTATION_FILE_EXTENSIONS: tuple[str, ...] = (".md", ".mdx")
 FRONTEND_CONFIG_GLOBS: tuple[str, ...] = (
     "tailwind.config.*",
     "vite.config.*",
@@ -155,9 +157,11 @@ def extract_human_note(body: str) -> str:
 def is_frontend_file(path: str) -> bool:
     """Return True if a changed file should be treated as frontend code."""
     normalized = path.lstrip("./")
+    lower = normalized.lower()
+    if lower.endswith(DOCUMENTATION_FILE_EXTENSIONS):
+        return False
     if any(normalized.startswith(prefix) for prefix in FRONTEND_PATH_PREFIXES):
         return True
-    lower = normalized.lower()
     if any(lower.endswith(ext) for ext in FRONTEND_FILE_EXTENSIONS):
         return True
     name = normalized.split("/")[-1]

.github/scripts/tests/test_pr_description.py

@@ -8,6 +8,8 @@
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
 from check_pr_description import (
+    is_frontend_file,
+    touches_frontend,
     extract_linked_issue_numbers,
     extract_pr_type,
     validate_linked_issue_ready,
@@ -222,3 +224,23 @@ def test_bug_fix_with_video_link_no_errors():
 """
     errors = validate_bug_fix_evidence(body)
     assert errors == []
+
+
+def test_markdown_under_frontend_prefix_is_not_frontend():
+    assert not is_frontend_file("__tests__/router.md")
+    assert not is_frontend_file("src/notes.md")
+    assert not is_frontend_file("public/README.mdx")
+
+def test_markdown_outside_frontend_prefix_still_not_frontend():
+    assert not is_frontend_file("docs/README.md")
+
+def test_frontend_code_under_prefix_still_frontend():
+    assert is_frontend_file("src/app.tsx")
+    assert is_frontend_file("__tests__/routes/launch.test.tsx")
+    assert is_frontend_file("src/styles/main.css")
+
+def test_docs_only_change_does_not_require_frontend_evidence():
+    assert not touches_frontend(["__tests__/router.md", "docs/README.md"])
+
+def test_mixed_change_still_requires_frontend_evidence():
+    assert touches_frontend(["__tests__/router.md", "src/app.tsx"])

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.14.0"
+  ".": "1.15.0"
 }

AGENTS.md

@@ -74,6 +74,54 @@ One Canvas-owned PostHog client owns telemetry and app analytics.
 2. Add the function to the hook's `return` object
 3. Destructure and call it from the component: `const { trackFoo } = useTracking()`
 
+### Event dictionary: onboarding_link_clicked
+
+One stable event for every onboarding link/CTA click. New onboarding links must
+reuse this contract (extend the unions in `use-tracking.ts`), never add one-off
+events per destination.
+
+Properties (all values controlled enums or booleans — never raw destination
+URLs, query params, or link text; `current_url` is the standard app-page common
+property, not a destination):
+- `link_id` (`OnboardingLinkId`): `configure_llm` | `start_conversation` |
+  `schedule_task` | `customize_agent` | `connect_mcp` | `join_slack` |
+  `open_docs`
+- `destination_type` (`OnboardingLinkDestinationType`): `community` |
+  `integration` | `documentation` | `settings` | `conversation` | `automation`
+- `surface` (`OnboardingLinkSurface`): `landing_checklist` |
+  `onboarding_modal` (reserved; no modal links are instrumented yet)
+- `checklist_item` (optional): the owning checklist item's `link_id`; set on
+  every `landing_checklist` emission, including `open_docs` clicks
+- `step_id` (optional): reserved for future onboarding-modal links
+- `is_external` (boolean): whether the destination leaves the app
+
+Instrumented CTAs (sidebar "Getting started" checklist; the row link and its
+preview action CTA intentionally share one `link_id` — same destination):
+
+| Checklist item | Row + preview action | Preview docs link |
+|---|---|---|
+| Add LLM API key | `configure_llm` / `settings` / internal | `open_docs` / `documentation` / external |
+| Start your first chat | `start_conversation` / `conversation` / internal | `open_docs` |
+| Schedule a task | `schedule_task` / `automation` / internal | `open_docs` |
+| Customize your agent | `customize_agent` / `settings` / internal | `open_docs` |
+| Connect an MCP integration | `connect_mcp` / `integration` / internal | `open_docs` |
+| Join the OpenHands Slack | `join_slack` / `community` / external | `open_docs` |
+
+Excluded CTAs (per the one-canonical-capture rule above):
+- Onboarding-modal wizard controls (back/next/skip/close, agent cards) →
+  covered by `onboarding_step_viewed` / `onboarding_completed` /
+  `onboarding_skipped`
+- Modal backend-connect CTAs and the backend form's docs links →
+  `backend_added` with `source: "onboarding"`
+- LLM settings help links inside the embedded settings screen (shared with
+  non-onboarding surfaces) → setup outcome captured by `settings_saved`
+- Recommended-automation cards → `prebuilt_automation_enabled`
+- Checklist expand/collapse toggle and the settings visibility switch → UI
+  state, not destination links
+
+Known limitation: middle-click (`auxclick`) opens are not captured; tracking
+uses React `onClick` only and never prevents default navigation.
+
 ### Env vars
 `VITE_POSTHOG_API_KEY` is the sole build-time PostHog key. Unconfigured source builds use staging; official release workflows set production explicitly. Precompiled consumers use runtime configuration instead.
 

README.md

@@ -96,7 +96,7 @@ docker run -it --rm \
   -p 8000:8000 \
   -v "$HOME/.openhands:/home/openhands/.openhands" \
   -v "${PROJECTS_PATH}:/projects" \
-  ghcr.io/openhands/agent-canvas:1.14.0 # x-release-please-version
+  ghcr.io/openhands/agent-canvas:1.15.0 # x-release-please-version
 ```
 
 **Windows (PowerShell / Windows Terminal):** See [README.windows.md](./README.windows.md) for the equivalent commands.

README.windows.md

@@ -12,7 +12,7 @@ For the main install options and overall context, see [README.md](./README.md).
 - A host directory for `PROJECTS_PATH` containing the project folders you want the agent to access (create it before starting the container)
 
 ```powershell
-docker pull ghcr.io/openhands/agent-canvas:1.14.0 # x-release-please-version
+docker pull ghcr.io/openhands/agent-canvas:1.15.0 # x-release-please-version
 
 $env:PROJECTS_PATH = Join-Path $HOME "projects"  # directory containing your project folders
 New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null
@@ -21,7 +21,7 @@ docker run -it --rm `
   -p 8000:8000 `
   -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
   -v "$($env:PROJECTS_PATH):/projects" `
-  ghcr.io/openhands/agent-canvas:1.14.0 # x-release-please-version
+  ghcr.io/openhands/agent-canvas:1.15.0 # x-release-please-version
 ```
 
 Open [http://localhost:8000/canvas](http://localhost:8000/canvas) in your browser.

__tests__/api/agent-server-adapter.test.ts

@@ -918,6 +918,93 @@ describe("toAppConversation", () => {
     updated_at: "2026-01-01T00:00:00Z",
   };
 
+  it("combines stats.usage_to_metrics into metrics when the backend doesn't set metrics directly (#16480)", () => {
+    const result = toAppConversation({
+      ...baseInfo,
+      stats: {
+        usage_to_metrics: {
+          agent: {
+            model_name: "agent-model",
+            accumulated_cost: 1.5,
+            max_budget_per_task: 10,
+            accumulated_token_usage: {
+              prompt_tokens: 100,
+              completion_tokens: 20,
+              cache_read_tokens: 5,
+              cache_write_tokens: 1,
+              context_window: 8000,
+              per_turn_token: 120,
+            },
+            costs: [],
+            response_latencies: [],
+            token_usages: [],
+          },
+          condenser: {
+            model_name: "condenser-model",
+            accumulated_cost: 0.5,
+            max_budget_per_task: null,
+            accumulated_token_usage: {
+              prompt_tokens: 40,
+              completion_tokens: 10,
+              cache_read_tokens: 0,
+              cache_write_tokens: 0,
+              context_window: 4000,
+              per_turn_token: 50,
+            },
+            costs: [],
+            response_latencies: [],
+            token_usages: [],
+          },
+        },
+      },
+    });
+
+    expect(result.metrics).toEqual({
+      accumulated_cost: 2,
+      max_budget_per_task: 10,
+      accumulated_token_usage: {
+        prompt_tokens: 140,
+        completion_tokens: 30,
+        cache_read_tokens: 5,
+        cache_write_tokens: 1,
+        context_window: 8000,
+        per_turn_token: 120,
+      },
+    });
+  });
+
+  it("prefers backend-provided metrics over stats.usage_to_metrics when both are present", () => {
+    const result = toAppConversation({
+      ...baseInfo,
+      metrics: { accumulated_cost: 3, max_budget_per_task: null },
+      stats: {
+        usage_to_metrics: {
+          agent: {
+            model_name: "agent-model",
+            accumulated_cost: 999,
+            max_budget_per_task: null,
+            accumulated_token_usage: null,
+            costs: [],
+            response_latencies: [],
+            token_usages: [],
+          },
+        },
+      },
+    });
+
+    expect(result.metrics?.accumulated_cost).toBe(3);
+  });
+
+  it("defaults metrics to a zero-cost snapshot when neither metrics nor stats are present", () => {
+    const result = toAppConversation({ ...baseInfo });
+
+    expect(result.metrics).toEqual({
+      accumulated_cost: 0,
+      max_budget_per_task: null,
+      accumulated_token_usage: null,
+    });
+  });
+
   it("falls back to the default title when the backend returns null", () => {
     const result = toAppConversation({ ...baseInfo, title: null });
     expect(result.title).toBe("Conversation 372eb");

__tests__/api/agent-server-conversation-service.test.ts

@@ -636,6 +636,50 @@ describe("AgentServerConversationService", () => {
       expect(result.items[0]?.sandbox_status).toBe("PAUSED");
     });
 
+    it("falls back to stats.usage_to_metrics when searchConversations omits metrics (#16480)", async () => {
+      const searchSpy = vi.fn().mockResolvedValue({
+        items: [
+          {
+            id: "conv-stats-only",
+            created_at: "2024-01-01",
+            updated_at: "2024-01-01",
+            stats: {
+              usage_to_metrics: {
+                default: {
+                  model_name: "test-model",
+                  accumulated_cost: 1.25,
+                  max_budget_per_task: null,
+                  accumulated_token_usage: {
+                    prompt_tokens: 100,
+                    completion_tokens: 50,
+                    cache_read_tokens: 0,
+                    cache_write_tokens: 0,
+                    context_window: 8000,
+                    per_turn_token: 150,
+                  },
+                  costs: [],
+                  response_latencies: [],
+                  token_usages: [],
+                },
+              },
+            },
+          },
+        ],
+        next_page_id: null,
+      });
+      mockConversationClient.mockReturnValue({
+        searchConversations: searchSpy,
+      });
+
+      const result =
+        await AgentServerConversationService.searchConversations(10);
+
+      expect(result.items[0]?.metrics?.accumulated_cost).toBe(1.25);
+      expect(
+        result.items[0]?.metrics?.accumulated_token_usage?.prompt_tokens,
+      ).toBe(100);
+    });
+
     it("preserves the launched Agent Profile through the wire normalizer", async () => {
       mockHttpGet.mockResolvedValue({
         data: [

__tests__/api/backend-registry/url-selection.test.ts

@@ -65,6 +65,73 @@ describe("withBackendSelectionParams", () => {
       `/conversations/abc?tab=files&${BACKEND_QUERY_PARAM}=local-1`,
     );
   });
+
+  it("keeps a fragment after existing query parameters intact and after the query", () => {
+    const path = withBackendSelectionParams(
+      "/conversations/abc?tab=files#detail",
+      {
+        backend: localBackend,
+        orgId: null,
+      },
+    );
+
+    expect(path).toBe(
+      `/conversations/abc?tab=files&${BACKEND_QUERY_PARAM}=local-1#detail`,
+    );
+  });
+
+  it("keeps a fragment on a path without query parameters after the query", () => {
+    const path = withBackendSelectionParams("/conversations/abc#detail", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=local-1#detail`,
+    );
+  });
+
+  it("does not treat a ? inside the fragment as a query separator", () => {
+    const path = withBackendSelectionParams("/conversations/abc#detail?x=1", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=local-1#detail?x=1`,
+    );
+  });
+
+  it("round-trips an empty fragment verbatim", () => {
+    const path = withBackendSelectionParams("/conversations/abc#", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(`/conversations/abc?${BACKEND_QUERY_PARAM}=local-1#`);
+  });
+
+  it("keeps the org id and the fragment together", () => {
+    const path = withBackendSelectionParams("/conversations/abc#detail", {
+      backend: cloudBackend,
+      orgId: "org-7",
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=prod&${ORG_QUERY_PARAM}=org-7#detail`,
+    );
+  });
+
+  it("keeps query data that itself contains a ?", () => {
+    const path = withBackendSelectionParams("/conversations/abc?next=/a?b=1", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?next=%2Fa%3Fb%3D1&${BACKEND_QUERY_PARAM}=local-1`,
+    );
+  });
 });
 
 describe("readBackendSelectionFromUrl", () => {