@stigmer/react 3.1.17 → 3.2.0

package/src/workflow/__tests__/useWorkflowExecutionPanel.test.ts

@@ -0,0 +1,297 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import { ArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import { FileChangeSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "../../execution/artifact-document";
+import {
+  FILE_CHANGE_DOCUMENT_ENTRY_ID,
+  fileChangeTabPath,
+} from "../../execution/file-change-document";
+import { AGENT_EXECUTION_DOCUMENT_ENTRY_ID } from "../../execution/agent-execution-document";
+import {
+  DIAGNOSIS_DOCUMENT_ENTRY_ID,
+  DIAGNOSIS_DOCUMENT_PATH,
+} from "../diagnosis-document";
+import {
+  useWorkflowExecutionPanel,
+  workflowArtifactTabPath,
+} from "../useWorkflowExecutionPanel";
+
+function artifact(id: string, displayName: string) {
+  return create(ArtifactSchema, {
+    metadata: { id, name: displayName },
+    spec: { displayName, contentType: "application/json" },
+  });
+}
+
+function fileChange(path: string) {
+  return create(FileChangeSchema, { path, changeType: FileChangeType.MODIFY });
+}
+
+describe("workflowArtifactTabPath", () => {
+  it("combines the immutable id with the display name so the tab LABEL is the basename", () => {
+    expect(workflowArtifactTabPath(artifact("art_1", "report.json"))).toBe(
+      "art_1/report.json",
+    );
+  });
+
+  it("gives distinct identities to same-named artifacts from different tasks", () => {
+    const a = workflowArtifactTabPath(artifact("art_1", "output.json"));
+    const b = workflowArtifactTabPath(artifact("art_2", "output.json"));
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("fileChangeTabPath", () => {
+  it("uses the change's path so the tab LABEL is the file's basename", () => {
+    expect(fileChangeTabPath(fileChange("src/app/page.tsx"))).toBe(
+      "src/app/page.tsx",
+    );
+  });
+
+  it("falls back to absolutePath for captures without a workspace-relative path", () => {
+    const c = create(FileChangeSchema, {
+      path: "",
+      absolutePath: "/tmp/scratch.txt",
+      changeType: FileChangeType.MODIFY,
+    });
+    expect(fileChangeTabPath(c)).toBe("/tmp/scratch.txt");
+  });
+});
+
+describe("useWorkflowExecutionPanel", () => {
+  it("starts collapsed on the artifacts view", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.view).toBe("artifacts");
+  });
+
+  it("opens and closes, preserving the view", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    act(() => result.current.openPanel());
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.view).toBe("artifacts");
+  });
+
+  it("openArtifact opens a preview tab in the shared artifact family and expands the panel", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    const a = artifact("art_1", "report.json");
+
+    act(() => result.current.openArtifact(a));
+
+    expect(result.current.isOpen).toBe(true);
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toEqual([
+      {
+        entryId: ARTIFACT_DOCUMENT_ENTRY_ID,
+        path: "art_1/report.json",
+        preview: true,
+      },
+    ]);
+  });
+
+  it("browsing artifacts reuses the one preview tab; pinArtifact makes it persistent", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    const a = artifact("art_1", "a.json");
+    const b = artifact("art_2", "b.json");
+
+    act(() => {
+      result.current.openArtifact(a);
+      result.current.openArtifact(b);
+    });
+    // Preview-tab semantics: the second open replaced the first.
+    expect(result.current.editorsStore.getSnapshot().editors).toHaveLength(1);
+    expect(
+      result.current.editorsStore.getSnapshot().editors[0].path,
+    ).toBe("art_2/b.json");
+
+    act(() => result.current.pinArtifact(b));
+    expect(
+      result.current.editorsStore.getSnapshot().editors[0].preview,
+    ).toBe(false);
+  });
+
+  it("openFileChange opens a preview tab in the file-change family and expands the panel", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    const c = fileChange("src/app/page.tsx");
+
+    act(() => result.current.openFileChange(c));
+
+    expect(result.current.isOpen).toBe(true);
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toEqual([
+      {
+        entryId: FILE_CHANGE_DOCUMENT_ENTRY_ID,
+        path: "src/app/page.tsx",
+        preview: true,
+      },
+    ]);
+  });
+
+  it("the preview slot is shared ACROSS families — browsing a change then an artifact reuses one tab", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => {
+      result.current.openFileChange(fileChange("src/a.ts"));
+      result.current.openArtifact(artifact("art_1", "report.json"));
+    });
+
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toHaveLength(1);
+    expect(editors[0].entryId).toBe(ARTIFACT_DOCUMENT_ENTRY_ID);
+  });
+
+  it("pinFileChange makes the change's tab persistent", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    const c = fileChange("src/a.ts");
+
+    act(() => {
+      result.current.openFileChange(c);
+      result.current.pinFileChange(c);
+    });
+
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors[0].preview).toBe(false);
+  });
+
+  it("a same-named change and artifact never collide (distinct virtual families)", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    const c = fileChange("report.json");
+    const a = artifact("art_1", "report.json");
+
+    act(() => {
+      result.current.openFileChange(c);
+      result.current.pinFileChange(c);
+      result.current.openArtifact(a);
+    });
+
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toHaveLength(2);
+    expect(new Set(editors.map((e) => e.entryId)).size).toBe(2);
+  });
+
+  it("openAgentExecution opens a preview tab in the transcript family and expands the panel", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => result.current.openAgentExecution("aex_1", "summarize-report"));
+
+    expect(result.current.isOpen).toBe(true);
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toEqual([
+      {
+        entryId: AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
+        path: "aex_1/summarize-report",
+        preview: true,
+      },
+    ]);
+  });
+
+  it("the transcript preview shares the one slot with artifacts and changes", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => {
+      result.current.openAgentExecution("aex_1", "call-agent");
+      result.current.openArtifact(artifact("art_1", "report.json"));
+    });
+
+    // Preview-tab semantics: the artifact open replaced the transcript.
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toHaveLength(1);
+    expect(editors[0].entryId).toBe(ARTIFACT_DOCUMENT_ENTRY_ID);
+  });
+
+  it("pinAgentExecution makes the transcript's tab persistent", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => {
+      result.current.openAgentExecution("aex_1", "call-agent");
+      result.current.pinAgentExecution("aex_1", "call-agent");
+    });
+
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors[0].preview).toBe(false);
+  });
+
+  it("two AGENT_CALL tasks calling the same agent open distinct transcript tabs", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => {
+      result.current.openAgentExecution("aex_1", "first-call");
+      result.current.pinAgentExecution("aex_1", "first-call");
+      result.current.openAgentExecution("aex_2", "second-call");
+    });
+
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toHaveLength(2);
+    expect(new Set(editors.map((e) => e.path)).size).toBe(2);
+  });
+
+  it("closing an editor keeps the panel open (the panel is more than tabs)", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+    const a = artifact("art_1", "a.json");
+    act(() => result.current.openArtifact(a));
+    act(() =>
+      result.current.closeEditor(ARTIFACT_DOCUMENT_ENTRY_ID, "art_1/a.json"),
+    );
+    expect(result.current.editorsStore.getSnapshot().editors).toHaveLength(0);
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("honors a custom default view", () => {
+    const { result } = renderHook(() =>
+      useWorkflowExecutionPanel({ defaultView: "usage" }),
+    );
+    expect(result.current.view).toBe("usage");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Diagnosis document (singleton editor tab — the tab IS the active state)
+// ---------------------------------------------------------------------------
+
+describe("useWorkflowExecutionPanel openDiagnosis", () => {
+  it("opens the diagnosis document as a pinned tab and expands the panel", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => result.current.openDiagnosis());
+
+    expect(result.current.isOpen).toBe(true);
+    expect(result.current.editorsStore.getSnapshot().editors).toEqual([
+      {
+        entryId: DIAGNOSIS_DOCUMENT_ENTRY_ID,
+        path: DIAGNOSIS_DOCUMENT_PATH,
+        preview: false,
+      },
+    ]);
+  });
+
+  it("re-invoking Diagnose focuses the existing tab — never a duplicate (singleton)", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => {
+      result.current.openDiagnosis();
+      result.current.openDiagnosis();
+    });
+
+    expect(result.current.editorsStore.getSnapshot().editors).toHaveLength(1);
+  });
+
+  it("the pinned diagnosis tab survives preview browsing (artifacts reuse their own slot)", () => {
+    const { result } = renderHook(() => useWorkflowExecutionPanel());
+
+    act(() => {
+      result.current.openDiagnosis();
+      result.current.openArtifact(artifact("art_1", "report.json"));
+    });
+
+    const { editors } = result.current.editorsStore.getSnapshot();
+    expect(editors).toHaveLength(2);
+    expect(editors.map((e) => e.entryId)).toContain(
+      DIAGNOSIS_DOCUMENT_ENTRY_ID,
+    );
+  });
+});

package/src/workflow/__tests__/useWorkflowExecutionRailViews.test.tsx

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import { ArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import { FileChangeSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type {
+  DerivedCostSummary,
+  DerivedTaskState,
+} from "../../internal/store/workflow-execution-event-store";
+import {
+  useWorkflowExecutionRailViews,
+  type UseWorkflowExecutionRailViewsOptions,
+} from "../useWorkflowExecutionRailViews";
+
+function artifact(id: string, displayName: string) {
+  return create(ArtifactSchema, {
+    metadata: { id, name: displayName },
+    spec: { displayName, contentType: "application/json" },
+  });
+}
+
+function fileChange(path: string) {
+  return create(FileChangeSchema, {
+    path,
+    changeType: FileChangeType.MODIFY,
+  });
+}
+
+const EMPTY_COST_SUMMARY: DerivedCostSummary = {
+  costConsumedMicros: 0n,
+  costRemainingMicros: -1n,
+  tokensConsumed: 0n,
+  tokensRemaining: -1n,
+  thresholdBreached: false,
+};
+
+const EMPTY_TASK_STATES: ReadonlyMap<string, DerivedTaskState> = new Map();
+
+/** Minimal valid options; tests override the fields under test. */
+function baseOptions(
+  overrides?: Partial<UseWorkflowExecutionRailViewsOptions>,
+): UseWorkflowExecutionRailViewsOptions {
+  return {
+    artifacts: [],
+    onOpenArtifact: vi.fn(),
+    fileChanges: [],
+    onOpenFileChange: vi.fn(),
+    costSummary: EMPTY_COST_SUMMARY,
+    taskStates: EMPTY_TASK_STATES,
+    ...overrides,
+  };
+}
+
+describe("useWorkflowExecutionRailViews", () => {
+  it("always offers Artifacts, Changes AND Usage — even with zero data (the always-on panel chip needs a full rail)", () => {
+    const { result } = renderHook(() =>
+      useWorkflowExecutionRailViews(baseOptions()),
+    );
+    expect(result.current.map((v) => v.id)).toEqual([
+      "artifacts",
+      "changes",
+      "usage",
+    ]);
+    expect(result.current[1].label).toBe("Changes");
+    expect(result.current[2].label).toBe("Usage");
+    // No badge for an empty list (a zero badge would be noise); Usage never
+    // carries a badge (cost is a quantity, not a countable collection).
+    expect(result.current[0].badge).toBeUndefined();
+    expect(result.current[1].badge).toBeUndefined();
+    expect(result.current[2].badge).toBeUndefined();
+  });
+
+  it("carries the artifact count as the Artifacts rail badge", () => {
+    const { result } = renderHook(() =>
+      useWorkflowExecutionRailViews(
+        baseOptions({
+          artifacts: [artifact("art_1", "a.json"), artifact("art_2", "b.json")],
+        }),
+      ),
+    );
+    expect(result.current[0].badge).toBe(2);
+  });
+
+  it("carries the changed-file count as the Changes rail badge", () => {
+    const { result } = renderHook(() =>
+      useWorkflowExecutionRailViews(
+        baseOptions({
+          fileChanges: [fileChange("src/a.ts"), fileChange("src/b.ts")],
+        }),
+      ),
+    );
+    expect(result.current[1].badge).toBe(2);
+  });
+
+  it("is referentially stable across re-renders with unchanged inputs (DD-010)", () => {
+    const options = baseOptions({
+      artifacts: [artifact("art_1", "a.json")],
+      fileChanges: [fileChange("src/a.ts")],
+    });
+    const { result, rerender } = renderHook(() =>
+      useWorkflowExecutionRailViews(options),
+    );
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+
+  it("never offers an Inspect view — per-task detail lives on the thread cards (T06)", () => {
+    const { result } = renderHook(() =>
+      useWorkflowExecutionRailViews(baseOptions()),
+    );
+    expect(result.current.some((v) => v.id === "inspect")).toBe(false);
+  });
+});

package/src/workflow/deriveWorkflowArtifactItems.ts

@@ -0,0 +1,59 @@
+// Pure derivation of workflow Artifact resources into artifact-row entries.
+// Domain: workflow (the Artifact-resource analog of useSessionArtifacts).
+
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import {
+  fromArtifact,
+  type ArtifactRowItem,
+} from "../execution/artifact-row-item.js";
+
+/** One workflow artifact paired with its presentational row view-model. */
+export interface WorkflowArtifactEntry {
+  /** The full Artifact resource — identity for open/download behavior. */
+  readonly artifact: Artifact;
+  /** The row view-model rendered by `ArtifactRowView`. */
+  readonly item: ArtifactRowItem;
+}
+
+/**
+ * Derives the Artifacts facet's row list from a workflow execution's
+ * artifacts (as returned by `useWorkflowExecutionArtifacts`).
+ *
+ * **Sorting:** alphabetical by display name (case-insensitive) — the
+ * file-explorer mental model where users scan by filename, matching
+ * `useSessionArtifacts`.
+ *
+ * **No dedup:** unlike the session model (where re-runs overwrite a sandbox
+ * path and the latest wins), workflow `Artifact` records are immutable and
+ * append-only — each is a distinct output, keyed by `metadata.id`.
+ *
+ * **Name collision detection:** when two artifacts share a display name,
+ * both rows carry the producing task (`source.task_name`) as a subtitle for
+ * disambiguation — the workflow analog of the session's parent-directory
+ * subtitle.
+ *
+ * Pure function (not a hook): callers memoize on their artifacts reference.
+ */
+export function deriveWorkflowArtifactItems(
+  artifacts: readonly Artifact[],
+): readonly WorkflowArtifactEntry[] {
+  const nameCount = new Map<string, number>();
+  for (const artifact of artifacts) {
+    const lower = displayNameOf(artifact).toLowerCase();
+    nameCount.set(lower, (nameCount.get(lower) ?? 0) + 1);
+  }
+
+  const entries = artifacts.map((artifact): WorkflowArtifactEntry => {
+    const hasNameCollision =
+      (nameCount.get(displayNameOf(artifact).toLowerCase()) ?? 0) > 1;
+    return { artifact, item: fromArtifact(artifact, hasNameCollision) };
+  });
+
+  return [...entries].sort((a, b) =>
+    a.item.name.localeCompare(b.item.name, undefined, { sensitivity: "base" }),
+  );
+}
+
+function displayNameOf(artifact: Artifact): string {
+  return artifact.spec?.displayName || artifact.metadata?.name || "Unnamed";
+}

package/src/workflow/deriveWorkflowUsageItems.ts

@@ -0,0 +1,73 @@
+// Pure derivation of per-task usage rows from derived task states.
+// Domain: workflow (the Usage-facet analog of deriveWorkflowArtifactItems).
+
+import type { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { DerivedTaskState } from "../internal/store/workflow-execution-event-store.js";
+import { kindToDisplayName } from "./kind-metadata.js";
+import { taskKindToString } from "./workflow-graph-conversions.js";
+
+const BIGINT_ZERO = BigInt(0);
+
+/** One per-task usage row rendered by the Usage facet's breakdown list. */
+export interface WorkflowUsageItem {
+  /** Task name — the row's identity and the selection-callback argument. */
+  readonly taskName: string;
+  /** Task kind enum (as reported by the event stream). */
+  readonly taskKind: WorkflowTaskKind;
+  /** Human-readable kind label (e.g. `"Agent Call"`), via kind metadata. */
+  readonly kindLabel: string;
+  /** Task lifecycle status at derivation time. */
+  readonly status: DerivedTaskState["status"];
+  /** Cost consumed by the task in micro-USD. */
+  readonly costMicros: bigint;
+  /** Tokens consumed by the task (live for running agent-call tasks). */
+  readonly tokensUsed: bigint;
+}
+
+/**
+ * Derives the Usage facet's per-task breakdown from an execution's derived
+ * task states (as returned by `useWorkflowExecutionEventStream`).
+ *
+ * **Zero-usage rows are dropped** (zero cost AND zero tokens): they carry no
+ * usage signal, and the viewer's snapshot-fallback task states (built when
+ * event persistence failed) zero out cost/tokens — without the filter that
+ * fallback would render as a table of fake `$0.00` rows instead of degrading
+ * honestly to the facet's aggregate/empty state.
+ *
+ * **Sorting:** cost descending, then tokens descending, then name — the most
+ * expensive task first, answering the facet's core question ("which task is
+ * burning my budget?"). Comparisons stay in `bigint` (no `Number()` coercion,
+ * which loses precision above 2^53).
+ *
+ * Pure function (not a hook): callers memoize on their task-states reference.
+ */
+export function deriveWorkflowUsageItems(
+  taskStates: ReadonlyMap<string, DerivedTaskState>,
+): readonly WorkflowUsageItem[] {
+  const items: WorkflowUsageItem[] = [];
+  for (const state of taskStates.values()) {
+    if (state.costMicros === BIGINT_ZERO && state.tokensUsed === BIGINT_ZERO) {
+      continue;
+    }
+    items.push({
+      taskName: state.taskName,
+      taskKind: state.taskKind,
+      kindLabel: kindToDisplayName(taskKindToString(state.taskKind)),
+      status: state.status,
+      costMicros: state.costMicros,
+      tokensUsed: state.tokensUsed,
+    });
+  }
+
+  return items.sort((a, b) => {
+    if (a.costMicros !== b.costMicros) {
+      return a.costMicros > b.costMicros ? -1 : 1;
+    }
+    if (a.tokensUsed !== b.tokensUsed) {
+      return a.tokensUsed > b.tokensUsed ? -1 : 1;
+    }
+    return a.taskName.localeCompare(b.taskName, undefined, {
+      sensitivity: "base",
+    });
+  });
+}

package/src/workflow/diagnosis-document.ts

@@ -0,0 +1,31 @@
+// Identity of the AI-diagnosis document tab in the workflow execution
+// panel's editor group. Domain: workflow — diagnosis (`WorkflowRepairCard` /
+// the Workflow Architect flow) is workflow-only, so unlike the shared
+// transcript/artifact/file-change families in execution/, this identity has
+// no session-side consumer and lives beside its host.
+//
+// Kept in its own module (not in WorkflowRepairCard.tsx) so behavior-only
+// consumers — useWorkflowExecutionPanel opens the tab, the viewer routes to
+// it — depend on the identity without pulling the component (and its
+// MessageThread/diff-graph subtree) into their module graph (DD-003
+// headless-first). Mirrors session/plan-document.ts, the other singleton.
+
+import { virtualEntryId } from "../internal/store/index.js";
+
+/**
+ * Virtual entry id of the diagnosis document tab. A SINGLETON, like the
+ * session's plan tab (and unlike the artifact/file-change/transcript
+ * families): one execution has one diagnosis conversation, and re-invoking
+ * Diagnose focuses the existing tab rather than minting another. The
+ * NUL-namespaced virtual id can never alias a real workspace entry, and its
+ * distinct `"diagnosis"` kind can never collide with the other families.
+ */
+export const DIAGNOSIS_DOCUMENT_ENTRY_ID = virtualEntryId("diagnosis");
+
+/**
+ * The diagnosis tab's path — doubles as its tab label. A stable, generic
+ * label is part of the singleton design: `editorKey(entryId, path)` is the
+ * tab's IDENTITY, so a per-run label would mint a new tab per invocation
+ * and shatter the open-or-focus semantics of `openDiagnosis`.
+ */
+export const DIAGNOSIS_DOCUMENT_PATH = "AI Diagnosis";

package/src/workflow/execution/index.ts

@@ -4,18 +4,3 @@ export {
   type EdgeExecutionState,
   type ForkProgress,
 } from "./derive-execution-overlays.js";
-
-export {
-  deriveWaterfallEntries,
-  deriveWaterfallScale,
-  type WaterfallEntry,
-  type WaterfallAttempt,
-  type WaterfallSpan,
-  type WaterfallScale,
-} from "./derive-waterfall-entries.js";
-
-export {
-  useWaterfallEntries,
-  type UseWaterfallEntriesOptions,
-  type UseWaterfallEntriesReturn,
-} from "./useWaterfallEntries.js";