From 162f5360078b5a5a945fab1c65aa5fb1f470f107 Mon Sep 17 00:00:00 2001 From: agentrelaybot Date: Thu, 19 Nov 2026 13:27:25 +0100 Subject: [PATCH 1/5] feat(sessions): Session intelligence view behind sessionIntelEnabled (default off) Adds a "Session intelligence" tab to the Sessions page (?tab=intel), modelled on the Overlaps view. It reads GET /v1/session-intel/workspace (contract session-intel-workspace/1) from the session read API with the existing read-API handoff token and workspace attestation, and shows: - a coverage strip: summaries X of Y active sessions with the newest summary's relative time; claims "unavailable" when sessionsWithClaims is null, else X of Y; "Claim extraction: off/unknown" when it is not "on"; a caveat that the view may be incomplete in every state; the fixed notes in plain words (the summary-search note is dropped: the dashboard has no summary search); - alerts grouped by class with plain labels (Rule broken, Conflicting decisions, Duplicate work, Working nearby, then Conflicting plans, Other, Unclassified), high urgency first in a group, with an urgency badge, the artifact, created and delivered times, links to every session, per-recipient acked / not acked, and evidence links; "No alerts" empty state with the coverage caveat; - live status as a table (title, short summary or "No summary yet", state, last active, open intents or "unknown" when hasClaims is null); - handoffs with summary, decisions and open intents. Gating mirrors coordinationOverlaps: DASHBOARD_SESSION_INTEL_ENABLED (strict true/false, unset = false) writes the strict boolean sessionIntelEnabled into runtime-config.js; the view also needs sessionReadApi. When off nothing is requested. Any 501 from the read API hides the tab and an opened ?tab=intel falls back to the list, as Overlaps does for its disabled 404. Review, adversarial pass: all API text (titles, summaries, claim titles, artifacts, notes) is rendered as React text nodes or attributes, no dangerouslySetInnerHTML; a test renders hostile markup in title, summary, intents, decisions and artifact and asserts no script/img/onerror element. Hrefs come only from sessionHref(sessionId, source, eventId) via URLSearchParams on the app base path; a "javascript:" source stays a query value (tested). The read reuses readApiGet (bearer in memory, credentials omitted, redirect error, X-Relayhistory-Workspace-Id attestation; tested with a mismatched workspace). No secrets, fixtures use fake ids. The load is keyed by workspace without keepPrevious so another workspace's view is never shown. Non-501 failures surface as errors, not as an empty view. Unknown classes, notes and claimsExtraction values degrade to Unclassified / verbatim / unknown instead of failing the parse or implying coverage. Review, contextual pass: same shape as Overlaps (runtime flag in docker/40-runtime-config.sh and app-path RuntimeConfig, *-api.ts with a viewEnabled gate, fixture, panel, tab link with aria-current, redirect when unavailable, docs paragraph in docs/repository-guide.md). Uses the shell Card/Badge/Empty/Skeleton components and Tailwind utilities only; no new page CSS. Field names follow src/session-read-api/session-intel-workspace.ts. Validation: npm ci; npm run check (eslint 0 warnings, vitest 68 files / 1038 tests, tsc -b and vite build) all pass. Co-Authored-By: Claude Opus 5.5 --- docker/40-runtime-config.sh | 8 + docs/repository-guide.md | 2 + src/app-path.ts | 1 + src/runtime-session-intel.test.ts | 31 + src/sessions/SessionIntelPanel.test.tsx | 229 +++++++ src/sessions/SessionIntelPanel.tsx | 580 ++++++++++++++++++ src/sessions/SessionSearch.tsx | 2 +- .../SessionsPage.session-intel.test.tsx | 69 +++ src/sessions/SessionsPage.tsx | 38 ++ src/sessions/route.test.ts | 5 + src/sessions/route.ts | 14 +- src/sessions/session-intel-api.test.ts | 124 ++++ src/sessions/session-intel-api.ts | 99 +++ src/sessions/session-intel-fixture.ts | 142 +++++ 14 files changed, 1335 insertions(+), 9 deletions(-) create mode 100644 src/runtime-session-intel.test.ts create mode 100644 src/sessions/SessionIntelPanel.test.tsx create mode 100644 src/sessions/SessionIntelPanel.tsx create mode 100644 src/sessions/SessionsPage.session-intel.test.tsx create mode 100644 src/sessions/session-intel-api.test.ts create mode 100644 src/sessions/session-intel-api.ts create mode 100644 src/sessions/session-intel-fixture.ts diff --git a/docker/40-runtime-config.sh b/docker/40-runtime-config.sh index c0e1c5d..97d6b09 100755 --- a/docker/40-runtime-config.sh +++ b/docker/40-runtime-config.sh @@ -72,6 +72,13 @@ case "$coordination_overlaps" in true|false) ;; *) echo "40-runtime-config: DASHBOARD_COORDINATION_OVERLAPS_ENABLED must be true or false" >&2; exit 1 ;; esac +# The Sessions page's Session intelligence view (alerts, live status, handoffs). +# Off by default even when the read API serves /v1/session-intel/workspace. +session_intel="${DASHBOARD_SESSION_INTEL_ENABLED-false}" +case "$session_intel" in + true|false) ;; + *) echo "40-runtime-config: DASHBOARD_SESSION_INTEL_ENABLED must be true or false" >&2; exit 1 ;; +esac app_path="${DASHBOARD_APP_PATH:-/}" api_base_path="${DASHBOARD_API_BASE_PATH:-/cloud/api}" login_path="${DASHBOARD_LOGIN_PATH:-/login}" @@ -118,6 +125,7 @@ tmp="${target}.tmp.$$" printf ' sessionAgentFilter: %s,\n' "$session_agent_filter" printf ' sessionShortSummaries: %s,\n' "$session_short_summaries" printf ' coordinationOverlaps: %s,\n' "$coordination_overlaps" + printf ' sessionIntelEnabled: %s,\n' "$session_intel" printf ' appPath: %s,\n' "$(json_string "$app_path" DASHBOARD_APP_PATH)" printf ' apiBasePath: %s,\n' "$(json_string "$api_base_path" DASHBOARD_API_BASE_PATH)" printf ' loginPath: %s,\n' "$(json_string "$login_path" DASHBOARD_LOGIN_PATH)" diff --git a/docs/repository-guide.md b/docs/repository-guide.md index d505680..1831db5 100644 --- a/docs/repository-guide.md +++ b/docs/repository-guide.md @@ -149,6 +149,8 @@ A recorded short summary can appear under each session title in the list. Enable The Sessions page's Overlaps view (findings where agent sessions duplicated or collided with each other's work) is off by default. Enable `DASHBOARD_COORDINATION_OVERLAPS_ENABLED=true` to show it; the container accepts only literal `true` or `false` (unset defaults to false), and static hosts can supply the strict boolean `coordinationOverlaps` in the runtime config. It also needs `DASHBOARD_SESSION_READ_API_ENABLED=true` and a read API that serves `GET /v1/coordination/overlaps` (`READ_API_COORDINATION_OVERLAPS_ENABLED=true`). When it is off the page requests nothing from that endpoint, even if the read API serves it. +The Sessions page's Session intelligence view (`?tab=intel`: open coordination alerts grouped by class, live status of sessions active in the last two hours, and handoffs of idle or ended sessions from the last seven days, under a coverage strip) is off by default. Enable `DASHBOARD_SESSION_INTEL_ENABLED=true` to show it; the container accepts only literal `true` or `false` (unset defaults to false), and static hosts can supply the strict boolean `sessionIntelEnabled` in the runtime config. It also needs `DASHBOARD_SESSION_READ_API_ENABLED=true` and a read API that serves `GET /v1/session-intel/workspace` (contract `session-intel-workspace/1`, `READ_API_SESSION_INTEL_ENABLED=true`). When it is off the page requests nothing from that endpoint; when the read API answers `501` (not served, not migrated or not enabled for the workspace) the tab stays hidden. The view shows only titles, stored short summaries, claim titles, artifacts and ids, never transcript text, and its coverage strip says when summaries or claims are missing; claim-based alerts depend on claim extraction, which the read API reports as off or unknown. + The Timeline, Decision tree and Work graph views are ported from Cloud. They are off by default. Set `DASHBOARD_SESSION_VISUALIZATIONS_ENABLED=true` in the container to emit the strict boolean `sessionVisualizations` in the existing runtime config. Static-host configurations can supply that boolean directly. Missing, false or malformed values retain Conversation and never mount graph reads. Work graph requires the relaycontrol catalog identity contract (`sessionId`, `source`, `workspaceId`, `found`). Every request uses the existing `/cloud/api` cookie and workspace routes; the dashboard does not contact History directly. Explicit workspace links must match the signed-in workspace. Links to another workspace show a mismatch message without issuing session reads; relaycontrol has no workspace-switch endpoint. diff --git a/src/app-path.ts b/src/app-path.ts index 8005a8f..9f469e5 100644 --- a/src/app-path.ts +++ b/src/app-path.ts @@ -12,6 +12,7 @@ type RuntimeConfig = { sessionAgentFilter?: unknown; sessionShortSummaries?: unknown; coordinationOverlaps?: unknown; + sessionIntelEnabled?: unknown; analyticsEnabled?: unknown; }; diff --git a/src/runtime-session-intel.test.ts b/src/runtime-session-intel.test.ts new file mode 100644 index 0000000..76f768f --- /dev/null +++ b/src/runtime-session-intel.test.ts @@ -0,0 +1,31 @@ +import { execFileSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { runInNewContext } from "node:vm"; +import { expect, it } from "vitest"; + +it.each([undefined, "false", "true"])("writes the Session intelligence view gate as a strict boolean, off by default (%s)", (value) => { + const directory = mkdtempSync(join(tmpdir(), "dashboard-session-intel-")); + try { + const env: NodeJS.ProcessEnv = { ...process.env, DASHBOARD_HTML_ROOT: directory }; + if (value === undefined) delete env.DASHBOARD_SESSION_INTEL_ENABLED; + else env.DASHBOARD_SESSION_INTEL_ENABLED = value; + execFileSync("sh", [resolve("docker/40-runtime-config.sh")], { env, stdio: "pipe" }); + const context = { window: {} as { __AGENT_RELAY_DASHBOARD_CONFIG__?: { sessionIntelEnabled: unknown } } }; + runInNewContext(readFileSync(join(directory, "runtime-config.js"), "utf8"), context); + expect(context.window.__AGENT_RELAY_DASHBOARD_CONFIG__?.sessionIntelEnabled).toBe(value === "true"); + } finally { rmSync(directory, { recursive: true, force: true }); } +}); + +it.each(["", "yes", "TRUE", "1", " true ", "true\nfalse"])("refuses malformed Session intelligence view config without replacing existing config (%j)", (value) => { + const directory = mkdtempSync(join(tmpdir(), "dashboard-session-intel-")); + const target = join(directory, "runtime-config.js"); + try { + writeFileSync(target, "existing config"); + expect(() => execFileSync("sh", [resolve("docker/40-runtime-config.sh")], { + env: { ...process.env, DASHBOARD_HTML_ROOT: directory, DASHBOARD_SESSION_INTEL_ENABLED: value }, stdio: "pipe", + })).toThrow(); + expect(readFileSync(target, "utf8")).toBe("existing config"); + } finally { rmSync(directory, { recursive: true, force: true }); } +}); diff --git a/src/sessions/SessionIntelPanel.test.tsx b/src/sessions/SessionIntelPanel.test.tsx new file mode 100644 index 0000000..aba2752 --- /dev/null +++ b/src/sessions/SessionIntelPanel.test.tsx @@ -0,0 +1,229 @@ +import { render, screen, within } from "@testing-library/react"; +import { expect, it } from "vitest"; +import { + CLASS_LABELS, + CoverageStrip, + SessionIntelPanel, + alertClassLabel, + coverageNotes, + groupAlerts, +} from "./SessionIntelPanel"; +import { sessionIntelResponseSchema } from "./session-intel-api"; +import { + SESSION_INTEL_NOW, + emptySessionIntelFixture, + sessionIntelFixture, +} from "./session-intel-fixture"; + +const panel = (data = sessionIntelFixture) => ( + +); + +const coverage = sessionIntelFixture.coverage; + +it("maps alert classes to plain labels", () => { + expect(alertClassLabel("constraint_violation")).toBe("Rule broken"); + expect(alertClassLabel("intent_conflict")).toBe("Conflicting decisions"); + expect(alertClassLabel("collision")).toBe("Duplicate work"); + expect(alertClassLabel("overlap")).toBe("Working nearby"); + expect(alertClassLabel(null)).toBe("Unclassified"); + expect(alertClassLabel("a_future_class")).toBe("Unclassified"); + expect(alertClassLabel("toString")).toBe("Unclassified"); + expect(Object.keys(CLASS_LABELS).slice(0, 4)).toEqual([ + "constraint_violation", + "intent_conflict", + "collision", + "overlap", + ]); +}); + +it("the fixture matches the contract", () => { + expect(sessionIntelResponseSchema.parse(sessionIntelFixture)).toEqual(sessionIntelFixture); + expect(sessionIntelResponseSchema.parse(emptySessionIntelFixture)).toEqual(emptySessionIntelFixture); +}); + +it("orders groups rule broken, conflicting decisions, duplicate work, working nearby, high urgency first", () => { + const low = { ...sessionIntelFixture.alerts[1]!, advisoryId: "fake-low", urgency: "low" as const }; + const groups = groupAlerts([low, ...sessionIntelFixture.alerts, { ...low, advisoryId: "fake-null", class: null }]); + expect(groups.map((group) => group.label)).toEqual([ + "Rule broken", + "Conflicting decisions", + "Duplicate work", + "Working nearby", + "Unclassified", + ]); + expect(groups[2]!.alerts.map((alert) => alert.advisoryId)).toEqual([ + "fake-advisory-collision", + "fake-low", + ]); +}); + +it("renders alerts grouped by class with urgency, artifact, times, both session links and delivery", () => { + render(panel()); + const alerts = screen.getByRole("region", { name: "Alerts" }); + expect( + within(alerts).getAllByRole("heading", { level: 3 }).map((heading) => heading.textContent), + ).toEqual([ + "Rule broken (1)", + "Conflicting decisions (1)", + "Duplicate work (1)", + "Working nearby (1)", + ]); + const collision = within(alerts).getByText("migrations/0001_fake.sql").closest("[class*='p-4']")!; + const card = within(collision as HTMLElement); + expect(card.getByText("High")).toBeVisible(); + expect(card.getByText("Created")).toBeVisible(); + expect(card.getByText("Delivered")).toBeVisible(); + const links = card.getAllByRole("link").map((link) => link.getAttribute("href")); + expect(links).toEqual([ + "/?session=fake-session-a&source=codex&workspace=fake-workspace&from=tab%3Dintel", + "/?session=fake-session-b&source=claude&workspace=fake-workspace&from=tab%3Dintel", + "/?session=fake-session-b&source=claude&workspace=fake-workspace&event=fake-event-b&from=tab%3Dintel", + ]); + // A known title names the session; an untitled one falls back to its harness and id. + expect(card.getAllByText("Build the fake parser").length).toBeGreaterThan(0); + const delivery = card.getByRole("list", { name: "Delivery" }); + expect(delivery).toHaveTextContent("Build the fake parser: acked"); + expect(delivery).toHaveTextContent(/fake-session-b: not acked/); + // An undelivered alert says so. + const nearby = within(alerts).getByText("src/example-nearby.ts").closest("[class*='p-4']")!; + expect(nearby).toHaveTextContent(/Delivered\s*not yet/); + expect(within(nearby as HTMLElement).getByText("Low")).toBeVisible(); +}); + +it("renders live status with summaries, an explicit missing summary and unknown claims", () => { + render(panel()); + const table = screen.getByRole("table"); + const rows = within(table).getAllByRole("row"); + expect(rows).toHaveLength(3); + expect(rows[1]).toHaveTextContent("Build the fake parser"); + expect(rows[1]).toHaveTextContent("Adds a parser for the synthetic format."); + expect(rows[1]).toHaveTextContent("Active"); + expect(rows[1]).toHaveTextContent("2m ago"); + expect(rows[1]).toHaveTextContent("Ship the fake parser"); + expect(rows[2]).toHaveTextContent("No summary yet"); + expect(rows[2]).toHaveTextContent("Idle"); + expect(rows[2]).toHaveTextContent("unknown"); + expect(within(rows[1]!).getByRole("link")).toHaveAttribute( + "href", + "/?session=fake-session-a&source=codex&workspace=fake-workspace&from=tab%3Dintel", + ); +}); + +it("renders handoffs with summary, decisions and open intents", () => { + render(panel()); + const handoffs = screen.getByRole("region", { name: "Handoffs" }); + expect(handoffs).toHaveTextContent("Update the fake schema"); + expect(handoffs).toHaveTextContent("Done"); + expect(handoffs).toHaveTextContent("Moved the synthetic schema to version two."); + expect(handoffs).toHaveTextContent("Keep version one readable"); + expect(handoffs).toHaveTextContent("Remove version one later"); + expect(within(handoffs).getByRole("link")).toHaveAttribute( + "href", + "/?session=fake-session-c&source=gemini&workspace=fake-workspace&from=tab%3Dintel", + ); +}); + +it("shows claims as unavailable, never as zero, when the claims read failed", () => { + render(); + const strip = screen.getByRole("region", { name: "Coverage" }); + expect(strip).toHaveTextContent("Summaries: 1 of 2 active sessions, newest 5m ago"); + expect(strip).toHaveTextContent("Claims: unavailable"); + expect(strip).toHaveTextContent("Claim extraction: unknown"); + expect(strip).toHaveTextContent("Claims couldn't be read"); + expect(strip).not.toHaveTextContent("summaries/search"); +}); + +it("shows zero claims and an off extractor as they are", () => { + render( + , + ); + const strip = screen.getByRole("region", { name: "Coverage" }); + expect(strip).toHaveTextContent("Claims: 0 of 2"); + expect(strip).toHaveTextContent("Claim extraction: off"); + expect(strip).toHaveTextContent("depend on claim extraction"); +}); + +it("shows partial claims and never implies full coverage, even when every count matches", () => { + const { unmount } = render( + , + ); + expect(screen.getByRole("region", { name: "Coverage" })).toHaveTextContent("Claims: 1 of 2"); + unmount(); + render( + , + ); + const strip = screen.getByRole("region", { name: "Coverage" }); + expect(strip).not.toHaveTextContent("Claim extraction"); + expect(strip).toHaveTextContent("may be incomplete"); +}); + +it("rewrites the fixed notes in plain words and keeps unknown ones", () => { + expect( + coverageNotes([ + "alerts capped at 100", + "handoff search is not served here; use GET /v1/sessions/summaries/search", + "a new note", + ]), + ).toEqual(["Only the newest 100 alerts are shown; there may be more.", "a new note"]); +}); + +it("shows the empty states with the coverage caveat", () => { + render(panel(emptySessionIntelFixture)); + expect(screen.getByText("No alerts")).toBeVisible(); + expect(screen.getByText(/doesn't mean there are none/)).toBeVisible(); + expect(screen.getByText("No active sessions in the last 2 hours.")).toBeVisible(); + expect(screen.getByText("No idle or ended sessions in the last 7 days.")).toBeVisible(); + expect(screen.getByRole("region", { name: "Coverage" })).toHaveTextContent( + "Summaries: 0 of 0 active sessions, newest none", + ); + expect(screen.queryByRole("table")).not.toBeInTheDocument(); +}); + +it("renders hostile titles, summaries and artifacts as text, and links only from ids", () => { + const hostile = ''; + const data = structuredClone(sessionIntelFixture); + data.status[0]!.title = hostile; + data.status[0]!.shortSummary = hostile; + data.status[0]!.openIntents = [hostile]; + data.handoffs[0]!.decisions = [hostile]; + data.alerts[0]!.artifact = hostile; + data.alerts[0]!.sessions[0] = { source: "javascript:alert(3)//", sessionId: '">