feat: signals ui improvements (#915)

### TL;DR

Improved error handling and UI for the Inbox Signals feature, adding robust payload validation and better error states.

### What changed?

- Added robust error handling and payload validation for signal report artefacts
- Improved UI for loading, error, and empty states in the Inbox Signals tab
- Added specific error messages for different failure scenarios (permissions, not found, invalid payload)
- Created a developer console tool for local testing of different Inbox states
- Enhanced the UI with better truncation, loading skeletons, and responsive design
- Added type for `unavailableReason` to the `SignalReportArtefactsResponse` interface

Author: k11kirky

apps/twig/src/api/posthogClient.ts

@@ -1,6 +1,7 @@
 import { logger } from "@renderer/lib/logger";
 import type {
   RepoAutonomyStatus,
+  SignalReportArtefact,
   SignalReportArtefactsResponse,
   SignalReportsResponse,
   Task,
@@ -12,6 +13,87 @@ import { createApiClient, type Schemas } from "./generated";
 
 const log = logger.scope("posthog-client");
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function normalizeSignalReportArtefact(
+  value: unknown,
+): SignalReportArtefact | null {
+  if (!isObjectRecord(value)) {
+    return null;
+  }
+
+  const id = optionalString(value.id);
+  if (!id) {
+    return null;
+  }
+
+  const contentValue = isObjectRecord(value.content) ? value.content : null;
+  if (!contentValue) {
+    return null;
+  }
+
+  const content = optionalString(contentValue.content);
+  const sessionId = optionalString(contentValue.session_id);
+
+  // The backend may return empty content objects when binary decode fails.
+  if (!content && !sessionId) {
+    return null;
+  }
+
+  return {
+    id,
+    type: optionalString(value.type) ?? "unknown",
+    created_at: optionalString(value.created_at) ?? new Date(0).toISOString(),
+    content: {
+      session_id: sessionId ?? "",
+      start_time: optionalString(contentValue.start_time) ?? "",
+      end_time: optionalString(contentValue.end_time) ?? "",
+      distinct_id: optionalString(contentValue.distinct_id) ?? "",
+      content: content ?? "",
+      distance_to_centroid:
+        typeof contentValue.distance_to_centroid === "number"
+          ? contentValue.distance_to_centroid
+          : null,
+    },
+  };
+}
+
+function parseSignalReportArtefactsPayload(
+  value: unknown,
+): SignalReportArtefactsResponse {
+  const payload = isObjectRecord(value) ? value : null;
+  const rawResults = Array.isArray(payload?.results)
+    ? payload.results
+    : Array.isArray(value)
+      ? value
+      : [];
+
+  const results = rawResults
+    .map(normalizeSignalReportArtefact)
+    .filter((artefact): artefact is SignalReportArtefact => artefact !== null);
+  const count =
+    typeof payload?.count === "number" ? payload.count : results.length;
+
+  if (rawResults.length > 0 && results.length === 0) {
+    return {
+      results: [],
+      count: 0,
+      unavailableReason: "invalid_payload",
+    };
+  }
+
+  return {
+    results,
+    count,
+  };
+}
+
 export class PostHogAPIClient {
   private api: ReturnType<typeof createApiClient>;
   private _teamId: number | null = null;
@@ -551,23 +633,58 @@ export class PostHogAPIClient {
     const url = new URL(
       `${this.api.baseUrl}/api/projects/${teamId}/signal_reports/${reportId}/artefacts/`,
     );
-    const response = await this.api.fetcher.fetch({
-      method: "get",
-      url,
-      path: `/api/projects/${teamId}/signal_reports/${reportId}/artefacts/`,
-    });
+    const path = `/api/projects/${teamId}/signal_reports/${reportId}/artefacts/`;
 
-    if (!response.ok) {
-      throw new Error(
-        `Failed to fetch signal report artefacts: ${response.statusText}`,
-      );
-    }
+    try {
+      const response = await this.api.fetcher.fetch({
+        method: "get",
+        url,
+        path,
+      });
 
-    const data = await response.json();
-    return {
-      results: data.results ?? data ?? [],
-      count: data.count ?? data.results?.length ?? data?.length ?? 0,
-    };
+      if (!response.ok) {
+        const responseText = await response.text();
+        const unavailableReason =
+          response.status === 403
+            ? "forbidden"
+            : response.status === 404
+              ? "not_found"
+              : "request_failed";
+
+        log.warn("Signal report artefacts unavailable", {
+          teamId,
+          reportId,
+          status: response.status,
+          statusText: response.statusText,
+          body: responseText || undefined,
+        });
+
+        return { results: [], count: 0, unavailableReason };
+      }
+
+      const data = (await response.json()) as unknown;
+      const parsed = parseSignalReportArtefactsPayload(data);
+
+      if (parsed.unavailableReason) {
+        log.warn("Signal report artefacts payload did not match schema", {
+          teamId,
+          reportId,
+        });
+      }
+
+      return parsed;
+    } catch (error) {
+      log.warn("Failed to fetch signal report artefacts", {
+        teamId,
+        reportId,
+        error,
+      });
+      return {
+        results: [],
+        count: 0,
+        unavailableReason: "request_failed",
+      };
+    }
   }
 
   async getRepositoryReadiness(

apps/twig/src/renderer/App.tsx

@@ -34,6 +34,19 @@ function App() {
     return initializeConnectivityStore();
   }, []);
 
+  // Dev-only inbox demo command for local QA from the renderer console.
+  useEffect(() => {
+    if (import.meta.env.PROD) {
+      return;
+    }
+
+    void import("@features/inbox/devtools/inboxDemoConsole").then(
+      ({ registerInboxDemoConsoleCommand }) => {
+        registerInboxDemoConsoleCommand();
+      },
+    );
+  }, []);
+
   // Global workspace error listener for toasts
   useEffect(() => {
     const subscription = trpcVanilla.workspace.onError.subscribe(undefined, {