@stigmer/react 3.1.16 → 3.2.0

package/src/session/__tests__/observerAudience.test.tsx

@@ -0,0 +1,241 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Wiring-contract tests for the read-only `"observer"` audience (design
+// decision 012: channel-session observability).
+//
+// Two invariants are pinned:
+// 1. `audience="observer"` renders a pure transcript — no composer, no
+//    interaction callbacks on the thread, no decision surfaces — while the
+//    session panel (usage/artifacts inspection) stays available.
+// 2. A channel-originated session (the `stigmer.ai/channel-id` label)
+//    self-selects observer regardless of the host's audience, so a pasted
+//    /sessions/{id} URL can never render a send surface the server would
+//    refuse (channel viewers hold can_view only).
+// ---------------------------------------------------------------------------
+
+type CapturedProps = Record<string, unknown>;
+
+const composerProps: CapturedProps[] = [];
+vi.mock("../../composer", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../composer")>();
+  return {
+    ...actual,
+    SessionComposer: (props: CapturedProps) => {
+      composerProps.push(props);
+      return <div data-testid="composer-probe" />;
+    },
+  };
+});
+
+const threadProps: CapturedProps[] = [];
+vi.mock("../../execution/MessageThread", () => ({
+  MessageThread: (props: CapturedProps) => {
+    threadProps.push(props);
+    return <div data-testid="thread-probe" />;
+  },
+}));
+
+const fileReviewDockProps: CapturedProps[] = [];
+vi.mock("../../execution/FileReviewDock", () => ({
+  FileReviewDock: (props: CapturedProps) => {
+    fileReviewDockProps.push(props);
+    return <div data-testid="file-review-dock-probe" />;
+  },
+}));
+
+const setupTabProps: CapturedProps[] = [];
+vi.mock("../facets/SetupTab", () => ({
+  SetupTab: (props: CapturedProps) => {
+    setupTabProps.push(props);
+    return <div data-testid="setup-probe" />;
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Flow stub — the organism owns the hook; stub it to a loaded state whose
+// session the individual tests can shape (channel-labeled or plain).
+// ---------------------------------------------------------------------------
+
+const stubWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  removeEntry: vi.fn(),
+  clear: vi.fn(),
+};
+
+const stubConv = {
+  session: { spec: {} } as Record<string, unknown>,
+  isLoading: false,
+  loadError: null,
+  completedExecutions: [],
+  activeStreamExecution: null,
+  activePhase: null,
+  isStreaming: false,
+  isConnecting: false,
+  sendFollowUp: vi.fn(),
+  canSendFollowUp: true,
+  isSending: false,
+  sendError: null,
+  clearSendError: vi.fn(),
+  pendingUserMessage: null,
+  workspaceEntries: [],
+  mcpServerUsages: [],
+  skillRefs: [],
+  pendingApprovals: [],
+  submitApproval: vi.fn(),
+  submittingApprovalIds: new Set<string>(),
+  fileChangeSets: [],
+  submitFileDecision: vi.fn(),
+  submittingFileDecisionKeys: new Set<string>(),
+  fileDecisionErrors: new Map<string, Error>(),
+  streamError: null,
+  reconnectStream: vi.fn(),
+  approvalError: null,
+  retryLastSend: vi.fn(),
+};
+
+const stubSessionPageFlow = {
+  conv: stubConv,
+  harness: "native" as const,
+  executionTarget: undefined,
+  model: [undefined, vi.fn()] as const,
+  interactionMode: ["agent" as const, vi.fn()] as const,
+  agentRef: { org: "acme", slug: "support-bot" },
+  setAgentRef: vi.fn(),
+  resolution: null,
+  setResolution: vi.fn(),
+  isDefaultAgent: false,
+  mcpServerUsages: [],
+  setMcpServerUsages: vi.fn(),
+  skillRefs: [],
+  setSkillRefs: vi.fn(),
+  workspace: stubWorkspace,
+  sessionVariables: { entries: [], isEmpty: true, clear: vi.fn() },
+  autoApproveAll: false,
+  setAutoApproveAll: vi.fn(),
+  submitApproval: vi.fn(),
+  handleSubmit: vi.fn(),
+  submitError: null as Error | null,
+  displayExecution: null,
+  allExecutions: [],
+  sandboxWorkspaceRoot: undefined,
+};
+vi.mock("../useSessionPageFlow", () => ({
+  useSessionPageFlow: () => stubSessionPageFlow,
+}));
+
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({
+    agentExecution: {
+      uploadAttachment: vi.fn(),
+      getArtifactContent: vi.fn(),
+    },
+  }),
+}));
+
+import { SessionViewer } from "../SessionViewer";
+
+const CHANNEL_SESSION = {
+  metadata: {
+    id: "ses_1",
+    org: "acme",
+    labels: {
+      "stigmer.ai/channel-id": "ach_1",
+      "stigmer.ai/channel-external-user-key": "U0AB12CD3",
+    },
+  },
+  spec: {},
+};
+
+function lastThreadProps(): CapturedProps {
+  expect(threadProps.length).toBeGreaterThan(0);
+  return threadProps.at(-1)!;
+}
+
+function expectReadOnlyTranscript() {
+  // No composer mounted at all — read-only by construction, not a
+  // disabled state.
+  expect(composerProps).toHaveLength(0);
+  expect(screen.queryByTestId("composer-probe")).toBeNull();
+
+  // Every thread interaction affordance is unwired (they are opt-in via
+  // their callbacks).
+  const thread = lastThreadProps();
+  expect(thread.onApprovalSubmit).toBeUndefined();
+  expect(thread.onEditMessage).toBeUndefined();
+  expect(thread.onRetrySend).toBeUndefined();
+  expect(thread.onRetryExecution).toBeUndefined();
+  expect(thread.onBuildFromPlan).toBeUndefined();
+  expect(thread.planActionsDisabled).toBe(true);
+
+  // The file-review decision surface never mounts.
+  expect(fileReviewDockProps).toHaveLength(0);
+
+  // The session panel stays available — inspecting usage/artifacts is
+  // the point of observability.
+  expect(screen.getByRole("button", { name: "Show panel" })).toBeDefined();
+}
+
+beforeEach(() => {
+  composerProps.length = 0;
+  threadProps.length = 0;
+  fileReviewDockProps.length = 0;
+  setupTabProps.length = 0;
+  stubConv.session = { spec: {} };
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("SessionViewer — observer audience", () => {
+  it("observer: read-only transcript, no composer, panel available", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" audience="observer" />);
+
+    expectReadOnlyTranscript();
+  });
+
+  it("a channel-originated session forces observer even for integrator hosts", () => {
+    stubConv.session = CHANNEL_SESSION;
+
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    expectReadOnlyTranscript();
+  });
+
+  it("observer: the host's access slot is withheld from the panel", () => {
+    stubConv.session = CHANNEL_SESSION;
+
+    render(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        accessSlot={<button type="button">Manage access</button>}
+      />,
+    );
+
+    // Even inside the opened Config facet — observers hold neither
+    // can_grant_access nor can_view_access on a channel session, so the
+    // control is withheld rather than left to fail server-side.
+    fireEvent.click(screen.getByRole("button", { name: "Show panel" }));
+    fireEvent.click(screen.getByRole("radio", { name: "Config" }));
+    expect(setupTabProps.length).toBeGreaterThan(0);
+    expect(setupTabProps.at(-1)!.accessSlot).toBeUndefined();
+    expect(screen.queryByRole("button", { name: "Manage access" })).toBeNull();
+  });
+
+  it("a plain console session keeps its composer (no accidental forcing)", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    expect(composerProps.length).toBeGreaterThan(0);
+    const thread = lastThreadProps();
+    expect(thread.onApprovalSubmit).toBeDefined();
+    expect(thread.onRetrySend).toBeDefined();
+  });
+});

package/src/session/__tests__/useSessionPanel.test.ts

@@ -8,20 +8,17 @@ import {
 import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { useSessionPanel, type UseSessionPanelOptions } from "../useSessionPanel";
 import { PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH } from "../plan-document";
-import { ARTIFACT_DOCUMENT_ENTRY_ID } from "../artifact-document";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "../../execution/artifact-document";
 import { artifactKey } from "../useSessionArtifacts";
-import type { SelectedThreadItem } from "../../internal/store/selection-store";
 
 // ---------------------------------------------------------------------------
 // The unified-panel controller: collapsed-by-default state, the open-editor
 // group, and the rail-view FSM ported from the retired inspector tabs. The
 // FSM rules under test: explicit picks are sticky; auto-switching happens only
-// in an OPEN panel (arrivals/selections never auto-open); running⇄terminal
-// transitions reset stickiness.
+// in an OPEN panel (arrivals never auto-open); running⇄terminal transitions
+// reset stickiness.
 // ---------------------------------------------------------------------------
 
-const item = { kind: "toolCall" } as unknown as SelectedThreadItem;
-
 function renderPanel(initial?: Partial<UseSessionPanelOptions>) {
   return renderHook(
     (opts: UseSessionPanelOptions) => useSessionPanel(opts),
@@ -73,49 +70,6 @@ describe("useSessionPanel — open/collapse", () => {
   });
 });
 
-describe("useSessionPanel — selection (Inspect)", () => {
-  it("auto-surfaces Inspect for a selection while the panel is open", () => {
-    const { result } = renderPanel();
-    act(() => result.current.openPanel());
-    act(() => result.current.notifySelection(item));
-    expect(result.current.view).toBe("inspect");
-  });
-
-  it("never auto-opens a collapsed panel on selection", () => {
-    const { result } = renderPanel();
-    act(() => result.current.notifySelection(item));
-    expect(result.current.isOpen).toBe(false);
-    expect(result.current.view).toBe("files");
-  });
-
-  it("surfaces a selection made while collapsed when the panel opens", () => {
-    const { result } = renderPanel();
-    act(() => result.current.notifySelection(item));
-    act(() => result.current.openPanel());
-    expect(result.current.view).toBe("inspect");
-  });
-
-  it("yields to an explicit pick (sticky) over selection auto-switch", () => {
-    const { result } = renderPanel();
-    act(() => result.current.openPanel());
-    act(() => result.current.setView("usage"));
-    act(() => result.current.notifySelection(item));
-    expect(result.current.view).toBe("usage");
-  });
-
-  it("leaves Inspect (and unsticks) when the selection clears", () => {
-    const { result } = renderPanel();
-    act(() => result.current.openPanel());
-    act(() => result.current.notifySelection(item));
-    expect(result.current.view).toBe("inspect");
-    act(() => result.current.notifySelection(null));
-    expect(result.current.view).toBe("files");
-    // Unstuck: the next selection auto-surfaces Inspect again.
-    act(() => result.current.notifySelection(item));
-    expect(result.current.view).toBe("inspect");
-  });
-});
-
 describe("useSessionPanel — arrivals and phase", () => {
   it("auto-surfaces Changes on first write-back while the panel is open", () => {
     const { result, rerender } = renderPanel();
@@ -150,9 +104,9 @@ describe("useSessionPanel — arrivals and phase", () => {
       hasChanges: false,
     });
     expect(result.current.view).toBe("files");
-    // Unstuck: a selection now auto-surfaces Inspect.
-    act(() => result.current.notifySelection(item));
-    expect(result.current.view).toBe("inspect");
+    // Unstuck: the next arrival auto-switch takes effect again.
+    rerender({ phase: ExecutionPhase.EXECUTION_COMPLETED, hasChanges: true });
+    expect(result.current.view).toBe("changes");
   });
 });
 
@@ -345,15 +299,6 @@ describe("useSessionPanel — defaultView (home view)", () => {
     expect(result.current.view).toBe("configure");
   });
 
-  it("returns to defaultView (not files) when a selection clears", () => {
-    const { result } = renderPanel({ defaultView: "configure" });
-    act(() => result.current.openPanel());
-    act(() => result.current.notifySelection(item));
-    expect(result.current.view).toBe("inspect");
-    act(() => result.current.notifySelection(null));
-    expect(result.current.view).toBe("configure");
-  });
-
   it("defaults the home view to Explorer (files) when omitted", () => {
     const { result, rerender } = renderPanel({
       phase: ExecutionPhase.EXECUTION_IN_PROGRESS,

package/src/session/__tests__/useSessionRailViews.test.tsx

@@ -5,8 +5,8 @@ import { renderHook, cleanup } from "@testing-library/react";
 // useSessionRailViews composes the session facets as injected rail views for
 // the workspace surface. The facet components themselves have their own
 // suites; here we prove the composition rules — ordering, contextual
-// visibility (Changes/Artifacts only with data, Inspect only with a
-// selection), and count badges — by mocking the aggregation hooks.
+// visibility (Changes/Artifacts only with data), and count badges — by
+// mocking the aggregation hooks.
 // ---------------------------------------------------------------------------
 
 const writeBacksState = { hasWriteBacks: false, writeBackCount: 0 };
@@ -21,7 +21,6 @@ vi.mock("../useSessionArtifacts", () => ({
 
 import { useSessionRailViews } from "../useSessionRailViews";
 import type { SetupTabProps } from "../facets/SetupTab";
-import type { SelectedThreadItem } from "../../internal/store/selection-store";
 
 const sessionConfig = {
   agentRef: null,
@@ -42,7 +41,6 @@ function renderViews(
       allExecutions: [],
       org: "acme",
       sessionConfig,
-      selectedItem: null,
       ...overrides,
     }),
   );
@@ -57,7 +55,7 @@ afterEach(() => {
 });
 
 describe("useSessionRailViews", () => {
-  it("always offers Config and Usage; Changes/Artifacts/Inspect are contextual", () => {
+  it("always offers Config and Usage; Changes/Artifacts are contextual", () => {
     const { result } = renderViews();
     expect(result.current.map((v) => v.id)).toEqual(["configure", "usage"]);
   });
@@ -100,37 +98,17 @@ describe("useSessionRailViews", () => {
     expect(artifacts?.badge).toBe(4);
   });
 
-  it("surfaces Inspect only while a thread item is selected", () => {
-    const selectedItem = { kind: "toolCall" } as unknown as SelectedThreadItem;
-    const { result, rerender } = renderHook(
-      ({ item }: { item: SelectedThreadItem | null }) =>
-        useSessionRailViews({
-          allExecutions: [],
-          org: "acme",
-          sessionConfig,
-          selectedItem: item,
-        }),
-      { initialProps: { item: selectedItem as SelectedThreadItem | null } },
-    );
-    expect(result.current.some((v) => v.id === "inspect")).toBe(true);
-    rerender({ item: null });
-    expect(result.current.some((v) => v.id === "inspect")).toBe(false);
-  });
-
-  it("keeps full inspector ordering: Config, Changes, Artifacts, Usage, Inspect", () => {
+  it("keeps full inspector ordering: Config, Changes, Artifacts, Usage", () => {
     writeBacksState.hasWriteBacks = true;
     writeBacksState.writeBackCount = 1;
     artifactsState.hasArtifacts = true;
     artifactsState.artifactCount = 1;
-    const { result } = renderViews({
-      selectedItem: { kind: "toolCall" } as unknown as SelectedThreadItem,
-    });
+    const { result } = renderViews();
     expect(result.current.map((v) => v.id)).toEqual([
       "configure",
       "changes",
       "artifacts",
       "usage",
-      "inspect",
     ]);
   });
 });

package/src/session/audience.ts

@@ -20,9 +20,23 @@
  *   org-level reads a guest principal cannot make (default-agent
  *   resolution, session→agent derivation, personal environments) and
  *   never fall back to the org's default agent.
+ * - `"observer"` — a read-only transcript for someone watching a
+ *   conversation they cannot participate in, e.g. a channel connector
+ *   or org admin reviewing a Slack/WhatsApp conversation the channel
+ *   runtime owns. No composer, no approval/edit/retry/build
+ *   affordances, no access management — the server enforces the same
+ *   boundary (channel viewers hold `can_view` only, never
+ *   `can_create_execution_in`), so the presentation simply never
+ *   offers what the caller could not do. The session panel stays
+ *   available read-only: usage, artifacts, and setup inspection are
+ *   the point of observability. `SessionViewer` also self-selects this
+ *   audience for channel-originated sessions (the
+ *   `stigmer.ai/channel-id` label), so every entry point — a
+ *   conversations list, a pasted URL — renders read-only without host
+ *   wiring.
  *
  * A preset rather than individual flags: each audience is a product
  * intent, and keeping it in one place lets the SDK evolve what that
  * presentation means without breaking embedders.
  */
-export type SessionAudience = "integrator" | "endUser" | "guest";
+export type SessionAudience = "integrator" | "endUser" | "guest" | "observer";

package/src/session/channelOrigin.ts

@@ -0,0 +1,45 @@
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+
+/**
+ * Metadata labels the cloud channel runtime stamps on every session it
+ * creates (one per external conversation). Mirrors
+ * `ChannelRuntimeConstants` in the Stigmer Cloud backend — the single
+ * continuity/audit key set for channel conversations. Console-created
+ * sessions never carry any of them.
+ */
+export const CHANNEL_SESSION_LABELS = {
+  /** The AgentChannel that originated the conversation. */
+  channelId: "stigmer.ai/channel-id",
+  /** The external platform user (e.g. Slack user id, WhatsApp wa_id). */
+  externalUserKey: "stigmer.ai/channel-external-user-key",
+  /** The provider-side conversation identity (thread ts, wa_id, ...). */
+  conversationKey: "stigmer.ai/channel-conversation-key",
+} as const;
+
+/**
+ * Whether a session was created by the channel runtime (a Slack/WhatsApp
+ * conversation) rather than by a person in the console.
+ *
+ * Channel viewers hold read-only access (`can_view` without
+ * `can_create_execution_in`), so session organisms use this to
+ * self-select the `"observer"` audience — every entry point renders
+ * read-only without host wiring.
+ */
+export function isChannelOriginSession(
+  session: Session | null | undefined,
+): boolean {
+  return Boolean(
+    session?.metadata?.labels?.[CHANNEL_SESSION_LABELS.channelId],
+  );
+}
+
+/**
+ * The external platform user a channel session belongs to, or `undefined`
+ * for non-channel sessions. An opaque provider id (e.g. `U0AB12CD3`) in
+ * v1 — display-name resolution is a future enhancement.
+ */
+export function channelSessionExternalUserKey(
+  session: Session | null | undefined,
+): string | undefined {
+  return session?.metadata?.labels?.[CHANNEL_SESSION_LABELS.externalUserKey];
+}

package/src/session/facets/index.ts

@@ -7,9 +7,6 @@ export type { ArtifactsTabProps } from "./ArtifactsTab.js";
 export { UsageTab } from "./UsageTab.js";
 export type { UsageTabProps } from "./UsageTab.js";
 
-export { InspectTab } from "./InspectTab.js";
-export type { InspectTabProps } from "./InspectTab.js";
-
 export { SetupTab } from "./SetupTab.js";
 export type {
   SetupTabProps,

package/src/session/index.ts

@@ -3,6 +3,11 @@ export type { ExecutionTargetOption } from "./execution-target.js";
 
 export type { RuntimeEnvProvider } from "./runtime-env.js";
 export type { SessionAudience } from "./audience.js";
+export {
+  CHANNEL_SESSION_LABELS,
+  isChannelOriginSession,
+  channelSessionExternalUserKey,
+} from "./channelOrigin.js";
 
 export { useCreateSession } from "./useCreateSession.js";
 export type {
@@ -129,12 +134,10 @@ export {
   PLAN_DOCUMENT_PATH,
 } from "./plan-document.js";
 
-// Artifact document — the editor-area rendering of an execution artifact
-// (mounted as an artifact-family virtual document) and the identity of its tabs.
-export { ARTIFACT_DOCUMENT_ENTRY_ID } from "./artifact-document.js";
-
-// Selection types (for platform builders composing their own Inspect facet)
-export type { SelectedThreadItem } from "../internal/store/selection-store.js";
+// Artifact document tab identity — promoted to execution/ (shared with the
+// workflow panel); re-exported here so `@stigmer/react`'s public export and
+// existing session-path importers are unchanged.
+export { ARTIFACT_DOCUMENT_ENTRY_ID } from "../execution/artifact-document.js";
 
 // Session facet components — the panel's rail views (Config et al.), also
 // independently importable (DD-003).