@obsunified/collector 2.2.0 → 2.2.3

package/src/plugins/connected-routes/deep-link-shapes.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { hrefForEntity, linksFromAi, linksFromEvalResults } from "./manifest";
+
+describe("connected-routes manifest link shapes", () => {
+	it("routes eval, service and ai_call entities to deep-linkable hashes", () => {
+		expect(hrefForEntity("eval", "case 1")).toBe("#/evaluations/case%201");
+		expect(hrefForEntity("service", "checkout")).toBe(
+			"#/service-map?service=checkout",
+		);
+		expect(hrefForEntity("ai_call", "call-1")).toBe("#/ai/calls/call-1");
+	});
+
+	it("carries the eval id and the ai call id in section links", () => {
+		const evals = linksFromEvalResults(
+			[
+				{
+					id: "eval-1",
+					actionId: "act-1",
+					projectId: "default",
+					evaluatorName: "groundedness",
+					evaluatorVersion: "1",
+					score: 1,
+					passed: 1,
+					reasoning: null,
+					rubricJson: null,
+				},
+			],
+			"Evals",
+		);
+		expect(evals.links[0].href).toBe("#/evaluations/eval-1");
+		const ai = linksFromAi(
+			[
+				{
+					callId: "call/1",
+					provider: "openai",
+					modelName: "gpt",
+				} as unknown as Parameters<typeof linksFromAi>[0][number],
+			],
+			"AI",
+		);
+		expect(ai.links[0].href).toBe("#/ai/calls/call%2F1");
+		expect(ai.links[0].entityId).toBe("call/1");
+	});
+});

package/src/plugins/connected-routes/manifest.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import {
+	hrefForEntity,
+	linksFromArtifacts,
+	linksFromEvalResults,
+	linksFromRetrievalEvents,
+	linksFromToolCalls,
+	MAX_LINKS_INLINE,
+	resolveFaultLocusTarget,
+} from "./manifest";
+
+// Tabs served by apps/web/src/app/router.ts (KNOWN_TABS). Generated hrefs
+// must start with one of these or the app falls back to Health.
+const ROUTER_TABS = new Set([
+	"health",
+	"investigate",
+	"traces",
+	"service-map",
+	"issues",
+	"logs",
+	"ai",
+	"evidence",
+	"usage",
+	"replay",
+	"alerts",
+	"users",
+	"agent-runs",
+	"actions",
+	"tool-calls",
+	"profiles",
+	"tool-reliability",
+	"evaluations",
+	"changes",
+	"findings",
+	"incidents",
+	"remediations",
+]);
+const tabOf = (href: string) =>
+	href.replace(/^#\//, "").split(/[/?#]/)[0] ?? "";
+
+describe("connected manifest hrefs target real router tabs", () => {
+	it("tool call overflow, retrievals, evals and artifacts avoid unknown tabs", () => {
+		const many = Array.from({ length: MAX_LINKS_INLINE + 1 }, (_, i) => ({
+			id: `t${i}`,
+			actionId: "a1",
+			toolName: "search",
+		}));
+		const hrefs = [
+			linksFromToolCalls(many as never, "Tools").links[0]?.href,
+			linksFromRetrievalEvents(
+				[
+					{
+						id: "r1",
+						actionId: "a1",
+						retrieverName: "kb",
+						totalResults: 3,
+					},
+				] as never,
+				"R",
+			).links[0]?.href,
+			linksFromEvalResults(
+				[{ id: "e1", actionId: "a1", evaluatorName: "g", passed: 1 }] as never,
+				"E",
+			).links[0]?.href,
+			linksFromArtifacts(
+				[
+					{
+						id: "x1",
+						actionId: "a1",
+						artifactName: "plan",
+						artifactType: "json",
+					},
+				] as never,
+				"A",
+			).links[0]?.href,
+		];
+		expect(hrefs).toEqual([
+			"#/tool-calls",
+			"#/actions/a1",
+			"#/evaluations/e1",
+			"#/actions/a1",
+		]);
+		for (const href of hrefs)
+			expect(ROUTER_TABS.has(tabOf(href ?? ""))).toBe(true);
+	});
+
+	it("hrefForEntity only emits router tabs for every evidence kind", () => {
+		for (const kind of [
+			"trace",
+			"span",
+			"alert",
+			"analysis",
+			"service",
+			"agent_run",
+			"action",
+			"tool_call",
+			"ai_call",
+			"profile",
+			"change",
+			"finding",
+			"incident",
+			"eval",
+			"log",
+			"replay",
+			"docs",
+		]) {
+			expect(ROUTER_TABS.has(tabOf(hrefForEntity(kind, "id-1"))), kind).toBe(
+				true,
+			);
+		}
+		expect(hrefForEntity("trace", "abc")).toBe("#/traces?trace=abc");
+		expect(hrefForEntity("alert", "al 1")).toBe("#/alerts?id=al%201");
+		expect(hrefForEntity("ai_call", "c1")).toBe("#/ai/calls/c1");
+	});
+});
+
+describe("resolveFaultLocusTarget", () => {
+	const trace = "a".repeat(32);
+	const span = "b".repeat(16);
+	it("classifies service nodes, bare services and spans", () => {
+		expect(
+			resolveFaultLocusTarget("service:prod:default:checkout-api"),
+		).toEqual({
+			entityKind: "service",
+			entityId: "service:prod:default:checkout-api",
+			href: "#/service-map?service=checkout-api",
+		});
+		expect(resolveFaultLocusTarget("checkout-api")).toMatchObject({
+			entityKind: "service",
+			href: "#/service-map?service=checkout-api",
+		});
+		expect(resolveFaultLocusTarget(`${trace}:${span}`)).toEqual({
+			entityKind: "span",
+			entityId: `${trace}:${span}`,
+			href: `#/traces?trace=${trace}&span=${span}`,
+		});
+		expect(resolveFaultLocusTarget(span)).toMatchObject({
+			entityKind: "span",
+			href: `#/evidence?kind=span&id=${span}`,
+		});
+	});
+});

package/src/plugins/connected-routes/manifest.ts

@@ -1,5 +1,6 @@
 import type {
 	CausalProofTier,
+	EvidenceEntityKind,
 	RelationshipCertainty,
 } from "@obsunified/types";
 import type {
@@ -58,7 +59,7 @@ export interface ConnectedLink {
 	href: string;
 	count?: number;
 	sample?: string;
-	entityKind?: ConnectedEntityKind | "trace" | "eval";
+	entityKind?: ConnectedEntityKind | EvidenceEntityKind;
 	entityId?: string;
 	source?: string;
 	confidence?: number;
@@ -347,7 +348,9 @@ export const linksFromAi = (
 		label: prefix,
 		links: calls.map((c) => ({
 			label: `${c.provider} · ${c.modelName}`,
-			href: `#/ai?id=${c.callId}`,
+			href: `#/ai/calls/${encodeURIComponent(c.callId)}`,
+			entityKind: "ai_call",
+			entityId: c.callId,
 		})),
 	};
 };
@@ -454,7 +457,7 @@ export const linksFromToolCalls = (
 			links: [
 				{
 					label: `${calls.length} tool calls`,
-					href: `#/tools`,
+					href: `#/tool-calls`,
 					count: calls.length,
 					sample: truncate(calls[0].toolName),
 					entityKind: "tool_call",
@@ -491,7 +494,8 @@ export const linksFromRetrievalEvents = (
 		label: prefix,
 		links: events.map((r) => ({
 			label: `retrieve: ${r.retrieverName} (${r.totalResults} docs)`,
-			href: `#/retrieval-events/${r.id}`,
+			// No dedicated retrieval tab: the owning action's detail page lists it.
+			href: `#/actions/${encodeURIComponent(r.actionId)}`,
 		})),
 	};
 };
@@ -514,7 +518,9 @@ export const linksFromEvalResults = (
 		label: prefix,
 		links: results.map((e) => ({
 			label: `eval: ${e.evaluatorName} (${e.passed ? "passed" : "failed"})`,
-			href: `#/evals/${e.id}`,
+			// The Evaluations tab resolves this id to an eval case, falling back
+			// to the case saved from the same action.
+			href: `#/evaluations/${encodeURIComponent(e.id)}`,
 			entityKind: "eval",
 			entityId: e.id,
 			...metadataForAction?.(e.actionId),
@@ -537,7 +543,118 @@ export const linksFromArtifacts = (
 		label: prefix,
 		links: arts.map((a) => ({
 			label: `artifact: ${a.artifactName} (${a.artifactType})`,
-			href: `#/artifacts/${a.id}`,
+			// No dedicated artifact tab: the owning action's detail page lists it.
+			href: `#/actions/${encodeURIComponent(a.actionId)}`,
 		})),
 	};
 };
+
+/**
+ * Dashboard destination for an evidence entity, using only routes the web
+ * router (`apps/web/src/app/router.ts`) actually serves. Unknown kinds fall
+ * back to the evidence explorer so a link never lands on the Health tab.
+ */
+export const hrefForEntity = (kind: string, id: string): string => {
+	const enc = encodeURIComponent;
+	switch (kind) {
+		case "trace":
+			return `#/traces?trace=${enc(id)}`;
+		case "span": {
+			const [traceId, spanId] = id.split(":");
+			return spanId && traceId
+				? `#/traces?trace=${enc(traceId)}&span=${enc(spanId)}`
+				: `#/evidence?kind=span&id=${enc(id)}`;
+		}
+		case "alert":
+			return `#/alerts?id=${enc(id)}`;
+		case "analysis":
+			return "#/health";
+		case "service":
+			return `#/service-map?service=${enc(id)}`;
+		case "agent_run":
+			return `#/agent-runs/${enc(id)}`;
+		case "action":
+			return `#/actions/${enc(id)}`;
+		case "tool_call":
+			return `#/tool-calls/${enc(id)}`;
+		case "ai_call":
+			return `#/ai/calls/${enc(id)}`;
+		case "profile":
+			return `#/profiles/${enc(id)}`;
+		case "change":
+			return `#/changes/${enc(id)}`;
+		case "finding":
+			return `#/findings/${enc(id)}`;
+		case "incident":
+			return `#/incidents/${enc(id)}`;
+		case "eval":
+			return `#/evaluations/${enc(id)}`;
+		case "log":
+			return `#/logs?id=${enc(id)}`;
+		case "replay":
+			return `#/replay?session=${enc(id)}`;
+		default:
+			return `#/evidence?kind=${enc(kind)}&id=${enc(id)}`;
+	}
+};
+
+export interface FaultLocusTarget {
+	entityKind: "service" | "span";
+	entityId: string;
+	href: string;
+}
+
+const HEX_SPAN_PAIR = /^[0-9a-f]{32}:[0-9a-f]{16}$/i;
+const HEX_SPAN_ID = /^[0-9a-f]{16}$/i;
+const NODE_KINDS = new Set([
+	"service",
+	"endpoint",
+	"database",
+	"queue",
+	"messaging_topic",
+	"topic",
+	"cache",
+	"external",
+]);
+
+/**
+ * A finding's `faultLocusEntityId` is a canonical ontology node id
+ * (`service:<env>:<ns>:<name>`, `endpoint:<env>:<ns>:<svc>:...`), a
+ * `traceId:spanId` pair, a bare span id, or a bare service name. Resolve it to
+ * the entity kind it really is and the surface that shows that kind.
+ */
+export const resolveFaultLocusTarget = (
+	faultLocusEntityId: string,
+): FaultLocusTarget => {
+	const id = faultLocusEntityId;
+	if (HEX_SPAN_PAIR.test(id)) {
+		return {
+			entityKind: "span",
+			entityId: id,
+			href: hrefForEntity("span", id),
+		};
+	}
+	if (HEX_SPAN_ID.test(id)) {
+		return {
+			entityKind: "span",
+			entityId: id,
+			href: hrefForEntity("span", id),
+		};
+	}
+	const segments = id.split(":");
+	if (segments.length > 1 && NODE_KINDS.has(segments[0] ?? "")) {
+		// service:<env>:<ns>:<name> and endpoint:<env>:<ns>:<svc>:... both carry
+		// the owning service name at index 3.
+		const name = segments[3] || segments[segments.length - 1] || id;
+		return {
+			entityKind: "service",
+			entityId: id,
+			href: hrefForEntity("service", name),
+		};
+	}
+	return {
+		entityKind: "service",
+		entityId: id,
+		href: hrefForEntity("service", id),
+	};
+};

package/src/plugins/connected-routes-links.test.ts

@@ -0,0 +1,96 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import { CollectorRuntime } from "../framework/collector";
+import type { CollectorEnv } from "../framework/env";
+import { recordInvestigationFinding } from "../lib/autosre-findings";
+import { openOrDeduplicateIncident } from "../lib/autosre-remediation-gate";
+import { createMigratedSqliteDb } from "../lib/test-utils/node-sqlite-db";
+import { connectedRoutesPlugin } from "./connected-routes";
+
+type Link = { href: string; entityKind?: string; entityId?: string };
+type Manifest = { up: { links: Link[] }[]; across: { links: Link[] }[] };
+
+const SERVICE_NODE = "service:prod:default:checkout-api";
+
+const setup = () => {
+	const db = createMigratedSqliteDb();
+	const app = new Hono<{ Bindings: CollectorEnv }>();
+	connectedRoutesPlugin.register(app, new CollectorRuntime());
+	const env = { DB: db as unknown as D1Database } as CollectorEnv;
+	const get = async (path: string) =>
+		(await (await app.request(path, {}, env)).json()) as Manifest;
+	return { db, get };
+};
+
+const openIncident = async (
+	db: ReturnType<typeof setup>["db"],
+	kind: "trace" | "alert",
+	anchorId: string,
+) =>
+	(
+		await openOrDeduplicateIncident(db, "default", {
+			environment: "prod",
+			targetNodeId: SERVICE_NODE,
+			symptomAnchorKind: kind,
+			symptomAnchorId: anchorId,
+			symptomFingerprint: `fp_${kind}`,
+			symptomCategory: `fp_${kind}`,
+		})
+	).incident;
+
+describe("connected links carry the real entity kind and a matching href", () => {
+	it("incident trigger signal for a trace anchor is a trace link", async () => {
+		const { db, get } = setup();
+		const incident = await openIncident(db, "trace", "trace-123");
+		const m = await get(
+			`/internal/connected/incident/${incident.id}?environment=prod`,
+		);
+		expect(m.up[0]?.links[0]).toMatchObject({
+			entityKind: "trace",
+			entityId: "trace-123",
+			href: "#/traces?trace=trace-123",
+		});
+		db.close();
+	});
+
+	it("incident trigger signal for an alert anchor stays an alert link", async () => {
+		const { db, get } = setup();
+		const incident = await openIncident(db, "alert", "rule-9");
+		const m = await get(
+			`/internal/connected/incident/${incident.id}?environment=prod`,
+		);
+		expect(m.up[0]?.links[0]).toMatchObject({
+			entityKind: "alert",
+			entityId: "rule-9",
+			href: "#/alerts?id=rule-9",
+		});
+		db.close();
+	});
+
+	it.each([
+		[SERVICE_NODE, "service", "#/service-map?service=checkout-api"],
+		["checkout-api", "service", "#/service-map?service=checkout-api"],
+	])("finding fault locus %s links as %s", async (locus, kind, href) => {
+		const { db, get } = setup();
+		const incident = await openIncident(db, "trace", "t1");
+		const finding = await recordInvestigationFinding(db, "default", {
+			environment: "prod",
+			incidentId: incident.id,
+			title: "Regression",
+			summary: "Errors after deploy",
+			causalProofTier: "corroborated_candidate",
+			symptomEntityKind: "trace",
+			symptomEntityId: "t1",
+			faultLocusEntityKind: "service",
+			faultLocusEntityId: locus,
+			causalChain: [],
+			citedEvidenceIds: [],
+		});
+		const m = await get(
+			`/internal/connected/finding/${finding.id}?environment=prod`,
+		);
+		const link = m.across[0]?.links[0];
+		expect(link).toMatchObject({ entityKind: kind, entityId: locus, href });
+		db.close();
+	});
+});

package/src/plugins/connected-routes.test.ts

@@ -470,7 +470,7 @@ describe("ConnectedRail manifest — raw signal action back-links", () => {
 			m.down.find((s) => s.label === "Evaluations for this span")?.links[0],
 		).toMatchObject({
 			label: "eval: groundedness (passed)",
-			href: "#/evals/eval-explicit",
+			href: "#/evaluations/eval-explicit",
 		});
 		expect(
 			m.related.find((s) => s.label === "Agent runs for this span")?.links[0],
@@ -749,7 +749,7 @@ describe("ConnectedRail manifest — raw signal action back-links", () => {
 		).toMatchObject({ href: "#/tool-calls/tool-explicit" });
 		expect(
 			m.down.find((s) => s.label === "Evaluations for this AI call")?.links[0],
-		).toMatchObject({ href: "#/evals/eval-explicit" });
+		).toMatchObject({ href: "#/evaluations/eval-explicit" });
 		expect(
 			m.related.find((s) => s.label === "Agent runs for this AI call")
 				?.links[0],
@@ -1280,7 +1280,7 @@ describe("ConnectedRail scenario acceptance contracts", () => {
 		const aiSection = userManifest.across.find((s) =>
 			s.label.toLowerCase().includes("ai call"),
 		);
-		expect(aiSection?.links[0].href).toBe("#/ai?id=ai-heavy-1");
+		expect(aiSection?.links[0].href).toBe("#/ai/calls/ai-heavy-1");
 
 		const sessionManifest = await fetch(
 			"/internal/connected/usage/sess-heavy?session_id=sess-heavy",