feat(civilization): add operator UI and client runtime

Author: erranter

apps/web/src/components/ChatView.tsx

@@ -2894,6 +2894,7 @@ export default function ChatView(props: ChatViewProps) {
           attempts: serverProjection.attempts,
           nodes: serverProjection.nodes,
           plans: serverProjection.plans,
+          providerTurns: serverProjection.providerTurns,
         }),
   });
   const draftTimelineEntries = optimisticUserMessages.map(

apps/web/src/components/chat/MessagesTimeline.logic.test.ts

@@ -4715,6 +4715,15 @@ describe("linked timeline resources", () => {
         kind: "message" as const,
         id: "final",
         createdAt: "2026-09-08T10:00:04Z",
+        attempt: {
+          id: RunAttemptId.make("attempt-context-inspector-meta"),
+          runId,
+          attemptOrdinal: 1,
+          rootNodeId: NodeId.make("node-context-inspector-meta"),
+          status: "completed" as const,
+          completedAt: null,
+        },
+        providerTurnOrdinal: 4,
         message: {
           id: MessageId.make("final"),
           role: "assistant" as const,
@@ -4736,6 +4745,10 @@ describe("linked timeline resources", () => {
     expect(collapsed.find((row) => row.id === "summary:created")).toMatchObject({
       resourceSummary: true,
     });
+    expect(collapsed.find((row) => row.id === "assistant-meta:final")).toMatchObject({
+      attemptId: "attempt-context-inspector-meta",
+      providerTurnOrdinal: 4,
+    });
     const expanded = deriveMessagesTimelineRows({
       ...common,
       timelineEntries,

apps/web/src/components/chat/MessagesTimeline.logic.ts

@@ -567,6 +567,8 @@ type MessagesTimelineRowContent =
       showAssistantCopyButton: boolean;
       assistantCopyStreaming: boolean;
       assistantTurnDiffSummary?: TurnDiffSummary | undefined;
+      attemptId?: RunAttemptId | undefined;
+      providerTurnOrdinal?: number | undefined;
       revertTurnCount?: number | undefined;
     }
   | {
@@ -577,6 +579,8 @@ type MessagesTimelineRowContent =
       message: ChatMessage;
       showAssistantCopyButton: boolean;
       assistantCopyStreaming: boolean;
+      attemptId?: RunAttemptId | undefined;
+      providerTurnOrdinal?: number | undefined;
     }
   | {
       kind: "event";
@@ -1213,6 +1217,10 @@ function attachTrailingToolGroupsToAssistant(
       message: row.message,
       showAssistantCopyButton: row.showAssistantCopyButton,
       assistantCopyStreaming: row.assistantCopyStreaming,
+      ...(row.attemptId === undefined ? {} : { attemptId: row.attemptId }),
+      ...(row.providerTurnOrdinal === undefined
+        ? {}
+        : { providerTurnOrdinal: row.providerTurnOrdinal }),
     });
   }
 
@@ -1804,6 +1812,10 @@ export function deriveMessagesTimelineRows(input: {
       showAssistantMeta,
       showAssistantCopyButton: showAssistantMeta,
       assistantCopyStreaming: timelineEntry.message.streaming || assistantResponseStillInProgress,
+      ...(timelineEntry.attempt === undefined ? {} : { attemptId: timelineEntry.attempt.id }),
+      ...(timelineEntry.providerTurnOrdinal === undefined
+        ? {}
+        : { providerTurnOrdinal: timelineEntry.providerTurnOrdinal }),
       assistantTurnDiffSummary:
         timelineEntry.message.role === "assistant"
           ? turnDiffSummaryByAssistantMessageId.get(timelineEntry.message.id)

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -178,6 +178,8 @@ import { McpAppFrame } from "./McpAppFrame";
 import { ChangedFilesCard } from "./ChangedFilesTree";
 import { useFileContextMenuHandler } from "../../fileContextMenu";
 import { useProject, useThreadShell } from "../../state/entities";
+import { useSettingsProjectGroups } from "../settings/useSettingsProjectGroups";
+import { resolveCivilizationContextSettingsLink } from "./civilizationContextInspectorLink";
 import {
   CHAT_TIMELINE_ANCHOR_OFFSET,
   readTimelinePosition,
@@ -2619,6 +2621,8 @@ function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "mess
             className="mt-1.5"
             projectedItem={row.projectedItem}
             message={row.message}
+            attemptId={row.attemptId}
+            providerTurnOrdinal={row.providerTurnOrdinal}
             showCopyButton={row.showAssistantCopyButton}
             copyStreaming={row.assistantCopyStreaming}
           />
@@ -2685,6 +2689,8 @@ function AssistantMetaTimelineRow({
         className="mt-0.5"
         projectedItem={row.projectedItem}
         message={row.message}
+        attemptId={row.attemptId}
+        providerTurnOrdinal={row.providerTurnOrdinal}
         showCopyButton={row.showAssistantCopyButton}
         copyStreaming={row.assistantCopyStreaming}
         alwaysVisible
@@ -2697,13 +2703,17 @@ function AssistantMessageMeta({
   className,
   projectedItem,
   message,
+  attemptId,
+  providerTurnOrdinal,
   showCopyButton,
   copyStreaming,
   alwaysVisible = false,
 }: {
   className?: string;
   projectedItem?: Extract<TimelineRow, { kind: "message" }>["projectedItem"];
   message: ChatMessage;
+  attemptId?: RunAttemptId | undefined;
+  providerTurnOrdinal?: number | undefined;
   showCopyButton: boolean;
   copyStreaming: boolean;
   alwaysVisible?: boolean;
@@ -2733,6 +2743,12 @@ function AssistantMessageMeta({
       {projectedItem?.item.type === "assistant_message" ? (
         <AssistantForkButton projectedItem={projectedItem} />
       ) : null}
+      <CivilizationContextInspectionLink
+        projectedItem={projectedItem}
+        message={message}
+        attemptId={attemptId}
+        providerTurnOrdinal={providerTurnOrdinal}
+      />
       {!message.streaming && (
         <Tooltip>
           <TooltipTrigger render={<p className="text-muted-foreground text-xs tabular-nums" />}>
@@ -2747,6 +2763,67 @@ function AssistantMessageMeta({
   );
 }
 
+function CivilizationContextInspectionLink({
+  projectedItem,
+  message,
+  attemptId,
+  providerTurnOrdinal,
+}: {
+  readonly projectedItem?: Extract<TimelineRow, { kind: "message" }>["projectedItem"];
+  readonly message: ChatMessage;
+  readonly attemptId?: RunAttemptId | undefined;
+  readonly providerTurnOrdinal?: number | undefined;
+}) {
+  const ctx = use(TimelineRowCtx);
+  const sourceThreadId = projectedItem?.sourceThreadId ?? null;
+  const sourceThread = useThreadShell(
+    sourceThreadId === null ? null : scopeThreadRef(ctx.activeThreadEnvironmentId, sourceThreadId),
+  );
+  const sourceProjectId = sourceThread?.projectId ?? null;
+  const projectGroups = useSettingsProjectGroups();
+  const search = (() => {
+    if (
+      sourceThreadId === null ||
+      sourceProjectId === null ||
+      message.runId === null ||
+      attemptId === undefined ||
+      providerTurnOrdinal === undefined
+    ) {
+      return null;
+    }
+    return resolveCivilizationContextSettingsLink({
+      groups: projectGroups,
+      environmentId: ctx.activeThreadEnvironmentId,
+      projectId: sourceProjectId,
+      threadId: sourceThreadId,
+      runId: message.runId,
+      attemptId,
+      providerTurnOrdinal,
+    });
+  })();
+
+  if (search === null) return null;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <Link
+            to="/settings/civilization"
+            search={search}
+            hash="civilization-context-inspector"
+            className="inline-flex size-6 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring/70"
+            aria-label="Inspect Civilization context for this turn"
+          >
+            <EyeIcon className="size-3.5" aria-hidden="true" />
+          </Link>
+        }
+      />
+      <TooltipPopup>Inspect Civilization context for this provider turn</TooltipPopup>
+    </Tooltip>
+  );
+}
+
 function AssistantCopyButton({
   message,
   showCopyButton,

apps/web/src/components/chat/civilizationContextInspectorLink.test.ts

@@ -0,0 +1,70 @@
+import { EnvironmentId, ProjectId, RunAttemptId, RunId, ThreadId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import type { SidebarProjectSnapshot } from "../../sidebarProjectGrouping";
+import { resolveCivilizationContextSettingsLink } from "./civilizationContextInspectorLink";
+
+const environmentId = EnvironmentId.make("environment-civilization-link");
+const projectId = ProjectId.make("project-civilization-link");
+const threadId = ThreadId.make("thread-civilization-link");
+const runId = RunId.make("run-civilization-link");
+const attemptId = RunAttemptId.make("attempt-civilization-link");
+const group = {
+  projectKey: "logical-project-key",
+  memberProjects: [
+    {
+      environmentId,
+      id: projectId,
+      physicalProjectKey: `${environmentId}:/repo`,
+    },
+  ],
+} as unknown as SidebarProjectSnapshot;
+
+describe("Civilization context Settings link", () => {
+  it("resolves the exact physical project and historical provider-turn identity", () => {
+    expect(
+      resolveCivilizationContextSettingsLink({
+        groups: [group],
+        environmentId,
+        projectId,
+        threadId,
+        runId,
+        attemptId,
+        providerTurnOrdinal: 3,
+      }),
+    ).toEqual({
+      project: "logical-project-key",
+      machine: environmentId,
+      checkout: `${environmentId}:/repo`,
+      contextThread: threadId,
+      contextRun: runId,
+      contextAttempt: attemptId,
+      contextTurn: 3,
+    });
+  });
+
+  it("does not broaden an unknown project or invalid provider turn", () => {
+    expect(
+      resolveCivilizationContextSettingsLink({
+        groups: [group],
+        environmentId,
+        projectId: ProjectId.make("missing-project"),
+        threadId,
+        runId,
+        attemptId,
+        providerTurnOrdinal: 3,
+      }),
+    ).toBeNull();
+    expect(
+      resolveCivilizationContextSettingsLink({
+        groups: [group],
+        environmentId,
+        projectId,
+        threadId,
+        runId,
+        attemptId,
+        providerTurnOrdinal: 0,
+      }),
+    ).toBeNull();
+  });
+});

apps/web/src/components/chat/civilizationContextInspectorLink.ts

@@ -0,0 +1,44 @@
+import type { EnvironmentId, ProjectId, RunAttemptId, RunId, ThreadId } from "@t3tools/contracts";
+
+import type { SidebarProjectSnapshot } from "../../sidebarProjectGrouping";
+
+export interface CivilizationContextSettingsLinkSearch {
+  readonly project: string;
+  readonly machine: EnvironmentId;
+  readonly checkout: string;
+  readonly contextThread: ThreadId;
+  readonly contextRun: RunId;
+  readonly contextAttempt: RunAttemptId;
+  readonly contextTurn: number;
+}
+
+/** Exact physical Settings target for one historical provider-turn inspection. */
+export function resolveCivilizationContextSettingsLink(input: {
+  readonly groups: ReadonlyArray<SidebarProjectSnapshot>;
+  readonly environmentId: EnvironmentId;
+  readonly projectId: ProjectId;
+  readonly threadId: ThreadId;
+  readonly runId: RunId;
+  readonly attemptId: RunAttemptId;
+  readonly providerTurnOrdinal: number;
+}): CivilizationContextSettingsLinkSearch | null {
+  if (!Number.isSafeInteger(input.providerTurnOrdinal) || input.providerTurnOrdinal < 1)
+    return null;
+  for (const group of input.groups) {
+    const member = group.memberProjects.find(
+      (candidate) =>
+        candidate.environmentId === input.environmentId && candidate.id === input.projectId,
+    );
+    if (member === undefined) continue;
+    return {
+      project: group.projectKey,
+      machine: input.environmentId,
+      checkout: member.physicalProjectKey,
+      contextThread: input.threadId,
+      contextRun: input.runId,
+      contextAttempt: input.attemptId,
+      contextTurn: input.providerTurnOrdinal,
+    };
+  }
+  return null;
+}