@stigmer/react 3.1.17 → 3.2.0

package/src/execution/useLiveAgentExecution.ts

@@ -0,0 +1,127 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import { isTerminalPhase } from "./execution-phases.js";
+import { useExecutionStream } from "./useExecutionStream.js";
+
+/** Return value of {@link useLiveAgentExecution}. */
+export interface UseLiveAgentExecutionReturn {
+  /**
+   * The freshest execution snapshot available: the live stream's while
+   * streaming, the fetched one otherwise. `null` while loading or when the
+   * execution does not exist.
+   */
+  readonly execution: AgentExecution | null;
+  /**
+   * Convenience extraction of `execution.status.phase`; returns
+   * `EXECUTION_PHASE_UNSPECIFIED` when `execution` is `null`.
+   */
+  readonly phase: ExecutionPhase;
+  /** `true` while the initial snapshot fetch is in flight (nothing to show yet). */
+  readonly isLoading: boolean;
+  /** `true` while live updates are arriving from the stream. */
+  readonly isStreaming: boolean;
+  /**
+   * `true` while a transient stream drop is being retried in the background.
+   * The last snapshot stays visible — surface a subtle affordance, not an error.
+   */
+  readonly isReconnecting: boolean;
+  /**
+   * Snapshot-fetch error, or the stream's terminal error (auto-reconnect
+   * exhausted). `null` when healthy. Not-found is NOT an error — it yields
+   * `execution: null` with no error, matching `useWorkflowExecution`.
+   */
+  readonly error: Error | null;
+  /**
+   * Recover from either failure mode: re-fetches the snapshot AND resets the
+   * stream (one retry affordance for consumers, whichever side failed).
+   */
+  readonly reconnect: () => void;
+}
+
+/**
+ * Behavior hook for a single {@link AgentExecution} that is live only while
+ * it needs to be: fetch the snapshot, stream only what is running.
+ *
+ * This is the single-execution analog of the session's canonical
+ * composition (`useSessionExecutions` GET for history + `useExecutionStream`
+ * for the active turn): a terminal execution is served entirely by one
+ * `agentExecution.get()` — never a subscription — while a running one layers
+ * the streaming pipeline on top of the fetched snapshot.
+ *
+ * - The snapshot fetch is DD-014 cached (`agent-execution:<id>`), so a
+ *   remount (e.g. returning to a transcript tab) renders instantly from the
+ *   previous result with a background refresh — no loading flash.
+ * - The stream starts only after the fetch proves the phase non-terminal;
+ *   `useExecutionStream` then owns the live lifecycle (rAF coalescing,
+ *   auto-reconnect, terminal-phase completion — DD-009/DD-017).
+ * - Once streaming, the stream's snapshot supersedes the fetched one (it is
+ *   always at least as fresh, including the terminal state the fetch missed).
+ *
+ * Pass `null` to skip entirely (stable no-op).
+ */
+export function useLiveAgentExecution(
+  executionId: string | null,
+): UseLiveAgentExecutionReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = executionId
+    ? async () => {
+        try {
+          return await stigmer.agentExecution.get(executionId);
+        } catch (err) {
+          if (isNotFound(err)) return null;
+          throw err;
+        }
+      }
+    : null;
+
+  const {
+    data: fetched,
+    isLoading,
+    error: fetchError,
+    refetch,
+  } = useFetch(fetchFn, [executionId, stigmer], null, {
+    cacheKey: executionId ? `agent-execution:${executionId}` : undefined,
+  });
+
+  // Gate the stream on the FETCHED phase, not the streamed one: the fetched
+  // snapshot never advances, so a run that terminates mid-stream does not
+  // flip this gate and unmount-thrash the subscription — useExecutionStream
+  // ends itself on the terminal snapshot (completion is phase-driven).
+  const fetchedPhase =
+    fetched?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  const shouldStream = fetched !== null && !isTerminalPhase(fetchedPhase);
+  const stream = useExecutionStream(shouldStream ? executionId : null);
+
+  const execution = stream.execution ?? fetched;
+  const phase =
+    execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+
+  const streamReconnect = stream.reconnect;
+  const reconnect = useCallback(() => {
+    refetch();
+    streamReconnect();
+  }, [refetch, streamReconnect]);
+
+  const error = fetchError ?? stream.error;
+  const { isStreaming, isReconnecting } = stream;
+
+  return useMemo(
+    () => ({
+      execution,
+      phase,
+      isLoading,
+      isStreaming,
+      isReconnecting,
+      error,
+      reconnect,
+    }),
+    [execution, phase, isLoading, isStreaming, isReconnecting, error, reconnect],
+  );
+}

package/src/index.ts

@@ -78,6 +78,7 @@ export {
   WorkspaceSummary,
   FileViewer,
   WorkspaceSurface,
+  PanelChip,
   ExplorerTree,
   virtualEntryId,
   isVirtualEntryId,
@@ -115,6 +116,8 @@ export type {
   WorkspaceSurfaceProps,
   SurfaceRailView,
   SurfaceVirtualDocument,
+  BuiltInViewId,
+  PanelChipProps,
   ExplorerTreeProps,
   OpenEditor,
   OpenFileOptions,
@@ -148,6 +151,9 @@ export {
   useSessionSearch,
   PENDING_SUBJECT,
   resolvedSubject,
+  CHANNEL_SESSION_LABELS,
+  isChannelOriginSession,
+  channelSessionExternalUserKey,
   SessionViewer,
   NewSessionViewer,
   useSessionPanel,
@@ -205,7 +211,6 @@ export type {
   SessionAudience,
   SetupTabProps,
   SetupTabMutationCallbacks,
-  SelectedThreadItem,
 } from "./session/index.js";
 
 // Activity — unified recent activity (sessions + workflow executions)
@@ -226,6 +231,7 @@ export {
   isTerminalPhase,
   useCreateAgentExecution,
   useExecutionStream,
+  useLiveAgentExecution,
   useAgentExecutionActions,
   useSubmitApproval,
   useFileReview,
@@ -295,8 +301,12 @@ export {
   useFileReviewRowState,
   useFileReviewRowChange,
   ArtifactRow,
+  ArtifactRowView,
+  fromExecutionArtifact,
+  fromArtifact,
   ArtifactContentRenderer,
   ArtifactContentBody,
+  ArtifactFileContent,
   ArtifactDocument,
   useArtifactInspection,
   ArtifactPreviewContent,
@@ -315,6 +325,7 @@ export {
   SessionVariablesInput,
   useExecutionArtifacts,
   useArtifactContent,
+  useArtifactContentById,
   useArtifactDownloadUrl,
   useArtifactDownload,
   useArtifactCopy,
@@ -328,6 +339,13 @@ export {
   writeBackDisplayName,
   FileChangesView,
   FileChangeDiff,
+  deriveExecutionFileChanges,
+  toFileDiffEntry,
+  FILE_CHANGE_DOCUMENT_ENTRY_ID,
+  fileChangeTabPath,
+  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
+  agentExecutionTabPath,
+  parseAgentExecutionTabPath,
   EmptyChangeNotice,
   isTextArtifact,
   formatArtifactSize,
@@ -342,6 +360,7 @@ export type {
   SharedAgentExecutionFields,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
+  UseLiveAgentExecutionReturn,
   UseAgentExecutionActionsOptions,
   UseAgentExecutionActionsReturn,
   UseSubmitApprovalReturn,
@@ -396,8 +415,11 @@ export type {
   UseApprovalResult,
   FileReviewContextValue,
   ArtifactRowProps,
+  ArtifactRowViewProps,
+  ArtifactRowItem,
   ArtifactContentRendererProps,
   ArtifactContentBodyProps,
+  ArtifactFileContentProps,
   ArtifactDocumentProps,
   ArtifactInspection,
   UseArtifactInspectionOptions,
@@ -415,6 +437,7 @@ export type {
   SessionVariablesInputProps,
   UseExecutionArtifactsReturn,
   UseArtifactContentReturn,
+  UseArtifactContentByIdReturn,
   UseArtifactDownloadUrlReturn,
   UseArtifactDownloadUrlOptions,
   UseArtifactDownloadReturn,
@@ -674,6 +697,7 @@ export {
   resolveSystemEnvVarValues,
   resolveDeclaredSystemEnvVars,
   EnvironmentPicker,
+  useToolCredentialsReadiness,
 } from "./environment/index.js";
 export type {
   UseEnvironmentReturn,
@@ -696,6 +720,7 @@ export type {
   SessionEnvPoolInput,
   UseSessionEnvPoolReturn,
   EnvironmentPickerProps,
+  ToolCredentialsReadiness,
 } from "./environment/index.js";
 
 // Identity Account — gate hook for ensuring the caller's identity account exists before app render
@@ -859,6 +884,7 @@ export { IdentityProvidersSection } from "./settings/index.js";
 export type { IdentityProvidersSectionProps } from "./settings/index.js";
 export { PlatformClientsSection } from "./settings/index.js";
 export { OAuthAppsSection } from "./settings/index.js";
+export { ChannelAppsSection } from "./settings/index.js";
 export { UsageSection } from "./settings/index.js";
 
 // User — app shell user menu
@@ -929,6 +955,33 @@ export type {
   OAuthAppDetailPanelProps,
 } from "./oauth-app/index.js";
 
+// Channel App — data hooks, mutation hooks, styled components, and Slack
+// setup helpers for bring-your-own channel apps (T04 item 2)
+export {
+  useChannelAppList,
+  useCreateChannelApp,
+  useUpdateChannelApp,
+  useDeleteChannelApp,
+  ChannelAppListPanel,
+  CreateChannelAppForm,
+  ChannelAppDetailPanel,
+  buildSlackChannelAppManifest,
+  slackChannelAppRedirectUrl,
+  slackChannelAppWebhookUrl,
+  SLACK_CHANNEL_APP_BOT_EVENTS,
+  SLACK_CHANNEL_APP_BOT_SCOPES,
+} from "./channel-app/index.js";
+export type {
+  UseChannelAppListReturn,
+  UseCreateChannelAppReturn,
+  UseUpdateChannelAppReturn,
+  UseDeleteChannelAppReturn,
+  ChannelAppListPanelProps,
+  CreateChannelAppFormProps,
+  ChannelAppDetailPanelProps,
+  SlackChannelAppManifestInput,
+} from "./channel-app/index.js";
+
 // Identity Provider — data hooks, mutation hooks, styled components, presets, and guided wizard for IdP management and SSO discovery
 export {
   useIdentityProviderList,
@@ -1021,6 +1074,46 @@ export type {
   ShareToolReadiness,
 } from "./sharing/index.js";
 
+// Channel — agent channels on external messaging platforms (Slack + WhatsApp):
+// the Channels tab panel, the per-provider connect dialogs, and the
+// AgentChannel hooks.
+export {
+  useAgentChannelList,
+  useAgentChannel,
+  useSaveAgentChannel,
+  agentChannelToInput,
+  useCreateAgentChannel,
+  useDeleteAgentChannel,
+  useConnectSlackChannel,
+  useInstallChannel,
+  useChannelToolReadiness,
+  useChannelSessions,
+  AgentChannelsPanel,
+  ConnectSlackDialog,
+  ConnectWhatsAppDialog,
+  ChannelCredentialsDialog,
+  ChannelToolCredentials,
+  ChannelConversationsDialog,
+} from "./channel/index.js";
+export type {
+  UseAgentChannelListReturn,
+  UseAgentChannelReturn,
+  UseSaveAgentChannelReturn,
+  UseCreateAgentChannelReturn,
+  UseDeleteAgentChannelReturn,
+  UseConnectSlackChannelReturn,
+  SlackConnectPhase,
+  UseInstallChannelReturn,
+  InstallChannelPhase,
+  UseChannelSessionsReturn,
+  AgentChannelsPanelProps,
+  ConnectSlackDialogProps,
+  ConnectWhatsAppDialogProps,
+  ChannelCredentialsDialogProps,
+  ChannelToolCredentialsProps,
+  ChannelConversationsDialogProps,
+} from "./channel/index.js";
+
 // Error — structured error display with classification, retry, and contextual guidance
 export { ErrorMessage, SecretFlowErrorGuide, isSecretFlowError } from "./error/index.js";
 export type { ErrorMessageProps, SecretFlowErrorGuideProps } from "./error/index.js";
@@ -1380,11 +1473,23 @@ export {
   WorkflowDetailView,
   WorkflowExecutionViewer,
   WorkflowExecutionHeader,
-  WorkflowExecutionTimeline,
-  WorkflowExecutionTaskPanel,
-  WorkflowExecutionCostPanel,
-  WorkflowExecutionArtifactPanel,
-  WorkflowExecutionApprovalCard,
+  useWorkflowExecutionPanel,
+  workflowArtifactTabPath,
+  DIAGNOSIS_DOCUMENT_ENTRY_ID,
+  DIAGNOSIS_DOCUMENT_PATH,
+  useWorkflowExecutionRailViews,
+  WorkflowArtifactsTab,
+  WorkflowChangesTab,
+  WorkflowUsageTab,
+  WorkflowArtifactDocument,
+  WorkflowAgentExecutionDocument,
+  useWorkflowArtifactDownload,
+  useWorkflowExecutionFileChanges,
+  enumerateAgentCallChildren,
+  agentCallChildrenSignature,
+  deriveWorkflowArtifactItems,
+  deriveWorkflowUsageItems,
+  WorkflowApprovalList,
   WorkflowFileReviewList,
   serializeWorkflowYaml,
   parseWorkflowYaml,
@@ -1467,6 +1572,19 @@ export {
   WorkflowTaskReviewGate,
   useReviewRenderer,
   useReviewPayload,
+  // S8: Workflow task thread (session-style center view)
+  projectThreadItems,
+  threadCardVariant,
+  useWorkflowThreadItems,
+  WorkflowTaskThread,
+  // T04: session-parity task cards — per-kind presentation seam (the
+  // workflow twin of registerToolPresenter)
+  resolveTaskPreview,
+  registerTaskPresenter,
+  getTaskPresenter,
+  defaultDisclosureForKind,
+  // S9: approval-boundary watcher (snapshot freshness + gate attention)
+  useApprovalBoundary,
 } from "./workflow/index.js";
 export type {
   TaskKindDescriptor,
@@ -1496,11 +1614,23 @@ export type {
   WorkflowDetailViewProps,
   WorkflowExecutionViewerProps,
   WorkflowExecutionHeaderProps,
-  WorkflowExecutionTimelineProps,
-  WorkflowExecutionTaskPanelProps,
-  WorkflowExecutionCostPanelProps,
-  WorkflowExecutionArtifactPanelProps,
-  WorkflowExecutionApprovalCardProps,
+  WorkflowExecutionPanelController,
+  UseWorkflowExecutionPanelOptions,
+  UseWorkflowExecutionRailViewsOptions,
+  WorkflowArtifactsTabProps,
+  WorkflowChangesTabProps,
+  WorkflowUsageTabProps,
+  AgentCallChild,
+  UseWorkflowExecutionFileChangesOptions,
+  UseWorkflowExecutionFileChangesReturn,
+  WorkflowArtifactDocumentProps,
+  WorkflowAgentExecutionDocumentProps,
+  WorkflowAgentExecutionHitl,
+  UseWorkflowArtifactDownloadReturn,
+  WorkflowArtifactEntry,
+  WorkflowUsageItem,
+  WorkflowApprovalListProps,
+  WorkflowApprovalSubmit,
   WorkflowFileReviewListProps,
   WorkflowFileDecisionSubmit,
   UseWorkflowYamlReturn,
@@ -1606,6 +1736,20 @@ export type {
   TaskOutcome,
   WorkflowTaskReviewGateProps,
   UseReviewPayloadReturn,
+  // S8: Workflow task thread (session-style center view) types
+  WorkflowThreadItem,
+  WorkflowThreadProgress,
+  WorkflowThreadProjection,
+  WorkflowThreadCardVariant,
+  WorkflowTaskThreadProps,
+  // T04: session-parity task cards — presentation seam types
+  WorkflowTaskPresenter,
+  WorkflowTaskPreview,
+  WorkflowTaskDisclosure,
+  // S10: in-thread HITL wiring type
+  WorkflowThreadHitl,
+  // S9: approval-boundary watcher types
+  ApprovalBoundaryCrossing,
 } from "./workflow/index.js";
 
 // ─── Dashboard (Unified Platform) ──────────────────────────────────────────

package/src/internal/DecisionButton.tsx

@@ -69,10 +69,11 @@ const VARIANT: Record<DecisionVariant, string> = {
 
 /**
  * The shared decision-action button for every approval surface — the agent
- * tool gate ({@link ApprovalCard}) and the two workflow approval cards
- * ({@link WorkflowTaskApprovalCard}, {@link WorkflowExecutionApprovalCard}).
+ * tool gate ({@link ApprovalCard}, which workflow surfaces reuse via
+ * `WorkflowApprovalList`) and the workflow human_input card
+ * ({@link WorkflowTaskApprovalCard}).
  *
- * One source of truth for the quiet, Cursor-grade button system so the three
+ * One source of truth for the quiet, Cursor-grade button system so the
  * surfaces can never visually drift, and so the spinner and base chrome live in
  * exactly one place. Every visual property flows through `--stgm-*` tokens.
  *

package/src/internal/__tests__/ThreadCardShell.test.tsx

@@ -0,0 +1,105 @@
+// Contract tests for the shared thread-card shell (T05/T06): the chrome
+// axes (bordered vs divider row, gate accent), the header gestures
+// (`expand` / `none` — `select` died with the Inspect drill-down, T06)
+// with their ARIA semantics, and the nested-button keydown guard. The two
+// consuming threads pin their own compositions; this file pins what they
+// share.
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import {
+  ThreadCardShell,
+  ThreadCardHeader,
+  ThreadCardBody,
+} from "../thread-card/index.js";
+
+afterEach(cleanup);
+
+describe("ThreadCardShell chrome", () => {
+  it("renders a bordered card by default and a divider row when nested", () => {
+    const { rerender, container } = render(
+      <ThreadCardShell cursorTarget="row">
+        <ThreadCardHeader>content</ThreadCardHeader>
+      </ThreadCardShell>,
+    );
+    const root = () =>
+      container.querySelector('[data-cursor-target="row"]') as HTMLElement;
+    expect(root().className).toContain("border-border-prominent");
+
+    rerender(
+      <ThreadCardShell cursorTarget="row" bordered={false}>
+        <ThreadCardHeader>content</ThreadCardHeader>
+      </ThreadCardShell>,
+    );
+    expect(root().className).toContain("border-b");
+    expect(root().className).not.toContain("border-border-prominent");
+  });
+
+  it("carries the gate accent", () => {
+    const { container } = render(
+      <ThreadCardShell cursorTarget="row" accent="warning">
+        <ThreadCardHeader>content</ThreadCardHeader>
+      </ThreadCardShell>,
+    );
+    const root = container.querySelector('[data-cursor-target="row"]') as HTMLElement;
+    expect(root.className).toContain("border-l-warning");
+  });
+});
+
+describe("ThreadCardHeader gestures", () => {
+  it("expand gesture: aria-expanded header toggling on click and keyboard", () => {
+    const onToggle = vi.fn();
+    render(
+      <ThreadCardHeader gesture={{ kind: "expand", expanded: false, onToggle }}>
+        row content
+      </ThreadCardHeader>,
+    );
+    const header = screen.getByRole("button");
+    expect(header.getAttribute("aria-expanded")).toBe("false");
+    expect(header.getAttribute("aria-pressed")).toBeNull();
+
+    fireEvent.click(header);
+    fireEvent.keyDown(header, { key: "Enter" });
+    fireEvent.keyDown(header, { key: " " });
+    expect(onToggle).toHaveBeenCalledTimes(3);
+  });
+
+  it("a nested action button's Enter never doubles as the header gesture", () => {
+    const onToggle = vi.fn();
+    const onAction = vi.fn();
+    render(
+      <ThreadCardHeader gesture={{ kind: "expand", expanded: false, onToggle }}>
+        <button
+          type="button"
+          aria-label="Copy"
+          onClick={(e) => {
+            e.stopPropagation();
+            onAction();
+          }}
+        >
+          c
+        </button>
+      </ThreadCardHeader>,
+    );
+
+    const nested = screen.getByRole("button", { name: "Copy" });
+    // The keydown bubbles to the header, whose guard must ignore it because
+    // the event target is the nested button, not the header itself.
+    fireEvent.keyDown(nested, { key: "Enter" });
+    fireEvent.click(nested);
+    expect(onAction).toHaveBeenCalledTimes(1);
+    expect(onToggle).not.toHaveBeenCalled();
+  });
+
+  it("none gesture renders a non-interactive layout row", () => {
+    render(<ThreadCardHeader>plain content</ThreadCardHeader>);
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+});
+
+describe("ThreadCardBody", () => {
+  it("carries the id for aria-controls wiring", () => {
+    render(<ThreadCardBody id="detail-1">body</ThreadCardBody>);
+    expect(document.getElementById("detail-1")?.textContent).toBe("body");
+  });
+});