@stigmer/react 3.1.0 → 3.1.2

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

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+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.
+// ---------------------------------------------------------------------------
+
+const writeBacksState = { hasWriteBacks: false, writeBackCount: 0 };
+const artifactsState = { hasArtifacts: false, artifactCount: 0 };
+
+vi.mock("../useSessionWriteBacks", () => ({
+  useSessionWriteBacks: () => writeBacksState,
+}));
+vi.mock("../useSessionArtifacts", () => ({
+  useSessionArtifacts: () => artifactsState,
+}));
+
+import { useSessionRailViews } from "../useSessionRailViews";
+import type { SetupTabProps } from "../facets/SetupTab";
+import type { SelectedThreadItem } from "../../internal/store/selection-store";
+
+const sessionConfig = {
+  agentRef: null,
+  isDefaultAgent: true,
+  mcpServerUsages: [],
+  skillRefs: [],
+  sessionVariables: null,
+  harness: "native",
+  executionTarget: undefined,
+  modelId: undefined,
+} as SetupTabProps;
+
+function renderViews(
+  overrides: Partial<Parameters<typeof useSessionRailViews>[0]> = {},
+) {
+  return renderHook(() =>
+    useSessionRailViews({
+      allExecutions: [],
+      org: "acme",
+      sessionConfig,
+      selectedItem: null,
+      ...overrides,
+    }),
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  writeBacksState.hasWriteBacks = false;
+  writeBacksState.writeBackCount = 0;
+  artifactsState.hasArtifacts = false;
+  artifactsState.artifactCount = 0;
+});
+
+describe("useSessionRailViews", () => {
+  it("always offers Config and Usage; Changes/Artifacts/Inspect are contextual", () => {
+    const { result } = renderViews();
+    expect(result.current.map((v) => v.id)).toEqual(["configure", "usage"]);
+  });
+
+  it("omits Config when no session configuration is provided", () => {
+    const { result } = renderViews({ sessionConfig: undefined });
+    expect(result.current.map((v) => v.id)).toEqual(["usage"]);
+  });
+
+  it("surfaces Changes with a write-back count badge", () => {
+    writeBacksState.hasWriteBacks = true;
+    writeBacksState.writeBackCount = 2;
+    const { result } = renderViews();
+    const changes = result.current.find((v) => v.id === "changes");
+    expect(changes?.badge).toBe(2);
+    expect(result.current.map((v) => v.id)).toEqual([
+      "configure",
+      "changes",
+      "usage",
+    ]);
+  });
+
+  it("surfaces Artifacts with a count badge", () => {
+    artifactsState.hasArtifacts = true;
+    artifactsState.artifactCount = 4;
+    const { result } = renderViews();
+    const artifacts = result.current.find((v) => v.id === "artifacts");
+    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", () => {
+    writeBacksState.hasWriteBacks = true;
+    writeBacksState.writeBackCount = 1;
+    artifactsState.hasArtifacts = true;
+    artifactsState.artifactCount = 1;
+    const { result } = renderViews({
+      selectedItem: { kind: "toolCall" } as unknown as SelectedThreadItem,
+    });
+    expect(result.current.map((v) => v.id)).toEqual([
+      "configure",
+      "changes",
+      "artifacts",
+      "usage",
+      "inspect",
+    ]);
+  });
+});

package/src/session/{inspector → facets}/ArtifactsTab.tsx

@@ -5,11 +5,11 @@ import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexe
 import {
   useSessionArtifacts,
   type SessionArtifactEntry,
-} from "../useSessionArtifacts";
-import { ArtifactCard } from "../../execution/ArtifactCard";
-import { ArtifactPreviewModal } from "../../execution/ArtifactPreviewModal";
-import { isPlanArtifact } from "../../library/detect-plan-artifact";
-import type { ApplyResourceResult } from "../../library/useApplyResource";
+} from "../useSessionArtifacts.js";
+import { ArtifactCard } from "../../execution/ArtifactCard.js";
+import { ArtifactPreviewModal } from "../../execution/ArtifactPreviewModal.js";
+import { isPlanArtifact } from "../../library/detect-plan-artifact.js";
+import type { ApplyResourceResult } from "../../library/useApplyResource.js";
 
 export interface ArtifactsTabProps {
   readonly executions: readonly AgentExecution[];
@@ -21,22 +21,44 @@ export interface ArtifactsTabProps {
    * action as the message-thread plan card.
    */
   readonly onImplementPlan?: () => void;
+  /**
+   * Open a plan in the session panel's plan document tab. When provided, a
+   * `plan.md` artifact routes there instead of the preview modal — the plan
+   * is a first-class document, not a popup. Non-plan artifacts keep the
+   * modal. When omitted (hosts without the plan tab) the modal remains for
+   * every artifact.
+   */
+  readonly onOpenPlan?: (executionId: string) => void;
 }
 
 /**
- * Artifacts facet for the SessionInspector.
+ * Artifacts facet for the session panel (a `useSessionRailViews` rail view).
  *
  * Wraps `useSessionArtifacts` → `ArtifactCard` list with
  * `ArtifactPreviewModal` — the same content as `ArtifactsWidget`
  * without the section heading.
  */
-export function ArtifactsTab({ executions, org, onApplied, onImplementPlan }: ArtifactsTabProps) {
+export function ArtifactsTab({
+  executions,
+  org,
+  onApplied,
+  onImplementPlan,
+  onOpenPlan,
+}: ArtifactsTabProps) {
   const { artifacts, hasArtifacts } = useSessionArtifacts(executions);
   const [previewEntry, setPreviewEntry] = useState<SessionArtifactEntry | null>(null);
 
-  const handlePreview = useCallback((entry: SessionArtifactEntry) => {
-    setPreviewEntry(entry);
-  }, []);
+  const handlePreview = useCallback(
+    (entry: SessionArtifactEntry) => {
+      // The plan opens as a document (the panel's plan tab), never a popup.
+      if (onOpenPlan && isPlanArtifact(entry.artifact)) {
+        onOpenPlan(entry.executionId);
+        return;
+      }
+      setPreviewEntry(entry);
+    },
+    [onOpenPlan],
+  );
 
   const handleClosePreview = useCallback(() => {
     setPreviewEntry(null);

package/src/session/{inspector → facets}/ChangesTab.tsx

@@ -1,23 +1,23 @@
 "use client";
 
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { useSessionWriteBacks } from "../useSessionWriteBacks";
-import { WriteBackCard } from "../../execution/WriteBackCard";
+import { useSessionWriteBacks } from "../useSessionWriteBacks.js";
+import { WriteBackCard } from "../../execution/WriteBackCard.js";
 
 export interface ChangesTabProps {
   readonly executions: readonly AgentExecution[];
 }
 
 /**
- * Changes facet for the SessionInspector — the session's git write-backs
+ * Changes facet for the session panel — the session's git write-backs
  * (branch/commit/PR), one `WriteBackCard` per entry.
  *
  * Local file changes deliberately do NOT render here: they live in the
  * transcript, where each stamped edit row shows its diff in place and the
  * per-turn decision bar carries the review controls and file list
  * (`FileReviewCard`). Duplicating them in a side panel gave the same change a
- * third rendering with no added authority. The tab therefore only surfaces
- * once a write-back exists (see `buildVisibleTabs`).
+ * third rendering with no added authority. The facet therefore only surfaces
+ * once a write-back exists (see `useSessionRailViews`).
  */
 export function ChangesTab({ executions }: ChangesTabProps) {
   const { writeBacks, hasWriteBacks } = useSessionWriteBacks(executions);

package/src/session/{inspector → facets}/InspectTab.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import type { SelectedThreadItem } from "../../internal/store/selection-store";
+import type { SelectedThreadItem } from "../../internal/store/selection-store.js";
 
 export interface InspectTabProps {
   readonly selectedItem: SelectedThreadItem | null;

package/src/session/{inspector → facets}/SetupTab.tsx

@@ -2,10 +2,10 @@
 
 import type { McpServerUsageInput, ResourceRef } from "@stigmer/sdk";
 import { cn } from "@stigmer/theme";
-import type { HarnessOption } from "../../models/harness";
-import { HARNESS_META } from "../../models/harness";
-import type { ExecutionTargetOption } from "../execution-target";
-import type { UseSessionVariablesReturn } from "../../execution/useSessionVariables";
+import type { HarnessOption } from "../../models/harness.js";
+import { HARNESS_META } from "../../models/harness.js";
+import type { ExecutionTargetOption } from "../execution-target.js";
+import type { UseSessionVariablesReturn } from "../../execution/useSessionVariables.js";
 
 /** Interactive mutation callbacks for config items in SetupTab. */
 export interface SetupTabMutationCallbacks {
@@ -32,11 +32,20 @@ export interface SetupTabProps {
    * buttons. When absent, sections are read-only (DD-011).
    */
   readonly mutations?: SetupTabMutationCallbacks;
+  /**
+   * Host-injected access management control (e.g. the Console's
+   * `ManageAccessButton`) rendered as the facet's final section. A slot keeps
+   * the SDK auth-agnostic (DD-004); the injected control owns its own
+   * visibility (permission gating), so this section renders no chrome of its
+   * own — an empty heading over a denied control would read as breakage.
+   */
+  readonly accessSlot?: React.ReactNode;
 }
 
 /**
  * Persistent session configuration panel (Configure tab) — shows agent,
- * MCP servers, skills, run config, and session variables.
+ * MCP servers, skills, run config, session variables, and the host's
+ * access management control (via `accessSlot`).
  *
  * Workspace management has moved to the dedicated Workspace tab.
  *
@@ -56,6 +65,7 @@ export function SetupTab({
   executionTarget,
   modelId,
   mutations,
+  accessSlot,
 }: SetupTabProps) {
   const hasSessionVars = sessionVariables != null && !sessionVariables.isEmpty;
 
@@ -86,6 +96,8 @@ export function SetupTab({
       {hasSessionVars && (
         <SessionVarsSection entries={sessionVariables.entries} />
       )}
+
+      {accessSlot && <section>{accessSlot}</section>}
     </div>
   );
 }

package/src/session/{inspector → facets}/UsageTab.tsx

@@ -1,15 +1,15 @@
 "use client";
 
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { useSessionUsage } from "../useSessionUsage";
-import { UsageWidget } from "../../execution/UsageWidget";
+import { useSessionUsage } from "../useSessionUsage.js";
+import { UsageWidget } from "../../execution/UsageWidget.js";
 
 export interface UsageTabProps {
   readonly executions: readonly AgentExecution[];
 }
 
 /**
- * Usage facet for the SessionInspector.
+ * Usage facet for the session panel (a `useSessionRailViews` rail view).
  *
  * Uses `useSessionUsage` to determine if data exists, then delegates
  * rendering to the existing `UsageWidget`. Shows an empty state when

package/src/session/{inspector → facets}/__tests__/ArtifactsTab.test.tsx

@@ -38,13 +38,17 @@ function createStigmerMock(): Stigmer {
   } as unknown as Stigmer;
 }
 
-function renderTab(onImplementPlan?: () => void) {
+function renderTab(
+  onImplementPlan?: () => void,
+  onOpenPlan?: (executionId: string) => void,
+) {
   return render(
     <StigmerContext.Provider value={createStigmerMock()}>
       <ArtifactsTab
         executions={[execution]}
         org="acme"
         onImplementPlan={onImplementPlan}
+        onOpenPlan={onOpenPlan}
       />
     </StigmerContext.Provider>,
   );
@@ -87,3 +91,33 @@ describe("ArtifactsTab — plan 'Build from plan' wiring", () => {
     expect(onImplementPlan).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("ArtifactsTab — plan routes to the plan document tab", () => {
+  it("routes a plan.md preview to onOpenPlan (no modal) when provided", () => {
+    const onOpenPlan = vi.fn();
+    renderTab(vi.fn(), onOpenPlan);
+
+    openPreviewFor("plan.md");
+
+    expect(onOpenPlan).toHaveBeenCalledWith("aex_1");
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("keeps the modal for non-plan artifacts even when onOpenPlan is provided", () => {
+    const onOpenPlan = vi.fn();
+    renderTab(vi.fn(), onOpenPlan);
+
+    openPreviewFor("notes.md");
+
+    expect(onOpenPlan).not.toHaveBeenCalled();
+    expect(document.querySelector("dialog")).toBeTruthy();
+  });
+
+  it("keeps the modal for plan.md when onOpenPlan is omitted (hosts without the plan tab)", () => {
+    renderTab(vi.fn());
+
+    openPreviewFor("plan.md");
+
+    expect(document.querySelector("dialog")).toBeTruthy();
+  });
+});

package/src/session/facets/__tests__/SetupTab.test.tsx

@@ -0,0 +1,44 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { SetupTab, type SetupTabProps } from "../SetupTab";
+
+// ---------------------------------------------------------------------------
+// The Config facet's access section: a host-injected slot with no chrome of
+// its own — the injected control (e.g. the Console's ManageAccessButton) owns
+// its visibility, so the facet must render nothing extra when the slot is
+// absent or the control gates itself away.
+// ---------------------------------------------------------------------------
+
+afterEach(cleanup);
+
+const BASE_PROPS: SetupTabProps = {
+  agentRef: null,
+  isDefaultAgent: false,
+  mcpServerUsages: [],
+  skillRefs: [],
+  sessionVariables: null,
+  harness: "native",
+  executionTarget: undefined,
+  modelId: undefined,
+};
+
+describe("SetupTab — access slot", () => {
+  it("renders the injected access control", () => {
+    render(
+      <SetupTab
+        {...BASE_PROPS}
+        accessSlot={<button type="button">Manage access</button>}
+      />,
+    );
+    expect(
+      screen.getByRole("button", { name: "Manage access" }),
+    ).toBeDefined();
+  });
+
+  it("renders no access section when the slot is absent", () => {
+    const { container } = render(<SetupTab {...BASE_PROPS} />);
+    expect(screen.queryByRole("button", { name: "Manage access" })).toBeNull();
+    // Only the four always-on sections (run config, agent, MCP, skills).
+    expect(container.querySelectorAll("section")).toHaveLength(4);
+  });
+});

package/src/session/facets/index.ts

@@ -0,0 +1,17 @@
+export { ChangesTab } from "./ChangesTab.js";
+export type { ChangesTabProps } from "./ChangesTab.js";
+
+export { ArtifactsTab } from "./ArtifactsTab.js";
+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,
+  SetupTabMutationCallbacks,
+} from "./SetupTab.js";

package/src/session/index.ts

@@ -1,125 +1,142 @@
-export { toProtoExecutionTarget, fromProtoExecutionTarget } from "./execution-target";
-export type { ExecutionTargetOption } from "./execution-target";
+export { toProtoExecutionTarget, fromProtoExecutionTarget } from "./execution-target.js";
+export type { ExecutionTargetOption } from "./execution-target.js";
 
-export type { RuntimeEnvProvider } from "./runtime-env";
-export type { SessionAudience } from "./audience";
+export type { RuntimeEnvProvider } from "./runtime-env.js";
+export type { SessionAudience } from "./audience.js";
 
-export { useCreateSession } from "./useCreateSession";
+export { useCreateSession } from "./useCreateSession.js";
 export type {
   SharedSessionFields,
   CreateSessionInput,
   CreateSessionResult,
   UseCreateSessionReturn,
-} from "./useCreateSession";
+} from "./useCreateSession.js";
 
-export { useUpdateSession } from "./useUpdateSession";
-export type { UseUpdateSessionReturn } from "./useUpdateSession";
+export { useUpdateSession } from "./useUpdateSession.js";
+export type { UseUpdateSessionReturn } from "./useUpdateSession.js";
 
-export { useSession } from "./useSession";
-export type { UseSessionReturn } from "./useSession";
+export { useSession } from "./useSession.js";
+export type { UseSessionReturn } from "./useSession.js";
 
-export { useSessionList } from "./useSessionList";
+export { useSessionList } from "./useSessionList.js";
 export type {
   UseSessionListOptions,
   UseSessionListReturn,
-} from "./useSessionList";
+} from "./useSessionList.js";
 
-export { useSessionExecutions } from "./useSessionExecutions";
-export type { UseSessionExecutionsReturn } from "./useSessionExecutions";
+export { useSessionExecutions } from "./useSessionExecutions.js";
+export type { UseSessionExecutionsReturn } from "./useSessionExecutions.js";
 
-export { useSessionConversation } from "./useSessionConversation";
+export { useSessionConversation } from "./useSessionConversation.js";
 export type {
   SendFollowUpOptions,
   UseSessionConversationReturn,
-} from "./useSessionConversation";
+} from "./useSessionConversation.js";
 
-export { useSessionArtifacts } from "./useSessionArtifacts";
+export { useSessionArtifacts } from "./useSessionArtifacts.js";
 export type {
   SessionArtifactEntry,
   UseSessionArtifactsReturn,
-} from "./useSessionArtifacts";
+} from "./useSessionArtifacts.js";
 
-export { useSessionWriteBacks } from "./useSessionWriteBacks";
+export { useSessionWriteBacks } from "./useSessionWriteBacks.js";
 export type {
   SessionWriteBackEntry,
   UseSessionWriteBacksReturn,
-} from "./useSessionWriteBacks";
+} from "./useSessionWriteBacks.js";
 
-export { useSessionFileChanges } from "./useSessionFileChanges";
-export type { UseSessionFileChangesReturn } from "./useSessionFileChanges";
+export { useSessionFileChanges } from "./useSessionFileChanges.js";
+export type { UseSessionFileChangesReturn } from "./useSessionFileChanges.js";
 
-export { useSessionUsage } from "./useSessionUsage";
+export { useSessionUsage } from "./useSessionUsage.js";
 export type {
   ModelCostEntry,
   UseSessionUsageReturn,
-} from "./useSessionUsage";
+} from "./useSessionUsage.js";
 
-export { useAgentRefFromSession } from "./useAgentRefFromSession";
-export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
+export { useAgentRefFromSession } from "./useAgentRefFromSession.js";
+export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession.js";
 
-export { useNewSessionFlow } from "./useNewSessionFlow";
+export { useNewSessionFlow } from "./useNewSessionFlow.js";
 export type {
   UseNewSessionFlowOptions,
   UseNewSessionFlowReturn,
-} from "./useNewSessionFlow";
+} from "./useNewSessionFlow.js";
 
-export { useSessionPageFlow } from "./useSessionPageFlow";
+export { useSessionPageFlow } from "./useSessionPageFlow.js";
 export type {
   UseSessionPageFlowOptions,
   UseSessionPageFlowReturn,
-} from "./useSessionPageFlow";
+} from "./useSessionPageFlow.js";
 
-export { usePersistedModel } from "./usePersistedModel";
-export type { UsePersistedModelReturn, UsePersistedModelOptions } from "./usePersistedModel";
+export { usePersistedModel } from "./usePersistedModel.js";
+export type { UsePersistedModelReturn, UsePersistedModelOptions } from "./usePersistedModel.js";
 
-export { useEditSessionPrep } from "./useEditSessionPrep";
-export type { UseEditSessionPrepReturn } from "./useEditSessionPrep";
+export { useEditSessionPrep } from "./useEditSessionPrep.js";
+export type { UseEditSessionPrepReturn } from "./useEditSessionPrep.js";
 
 export {
   CREATOR_AGENTS,
   parseDraftType,
   parseDraftParams,
-} from "./draft";
+} from "./draft.js";
 export type {
   DraftResourceType,
   DraftParams,
-} from "./draft";
+} from "./draft.js";
 
-export { groupSessionsByTime, groupSearchResultsByTime } from "./group-sessions";
-export type { SessionGroup, SearchResultGroup } from "./group-sessions";
+export { groupSessionsByTime, groupSearchResultsByTime } from "./group-sessions.js";
+export type { SessionGroup, SearchResultGroup } from "./group-sessions.js";
 
-export { useSessionSearch } from "./useSessionSearch";
+export { useSessionSearch } from "./useSessionSearch.js";
 export type {
   UseSessionSearchOptions,
   UseSessionSearchReturn,
-} from "./useSessionSearch";
+} from "./useSessionSearch.js";
 
 // SessionViewer — full-featured session viewer organism
-export { SessionViewer } from "./SessionViewer";
-export type { SessionViewerProps } from "./SessionViewer";
+export { SessionViewer } from "./SessionViewer.js";
+export type { SessionViewerProps } from "./SessionViewer.js";
 
 // NewSessionViewer — launcher organism with progressive Setup panel
-export { NewSessionViewer } from "./NewSessionViewer";
-export type { NewSessionViewerProps } from "./NewSessionViewer";
+export { NewSessionViewer } from "./NewSessionViewer.js";
+export type { NewSessionViewerProps } from "./NewSessionViewer.js";
 
-// Selection types (for platform builders using SessionInspector directly)
-export type { SelectedThreadItem } from "../internal/store/selection-store";
-
-// SessionInspector — tabbed right-side inspector panel
+// Unified session-panel controller — drives the WorkspaceSurface open-editor
+// group, the collapsed/open state, and the rail-view FSM (for platform
+// builders embedding the surface directly).
+export { useSessionPanel } from "./useSessionPanel.js";
+export type {
+  SessionPanelController,
+  UseSessionPanelOptions,
+} from "./useSessionPanel.js";
+
+// Plan draft — viewer-owned in-place edit of the session's current plan
+// (edit-as-input; the published plan.md artifact is never mutated).
+export { usePlanDraft, planDraftKey } from "./usePlanDraft.js";
+export type { PlanDraftController } from "./usePlanDraft.js";
+
+// Plan document — the editor-area plan surface (mounted as a virtual document
+// in the workspace surface) and the identity of its tab.
+export { PlanEditor } from "./PlanEditor.js";
+export type { PlanEditorProps } from "./PlanEditor.js";
+export { PlanStreamingDocument } from "./PlanStreamingDocument.js";
+export type { PlanStreamingDocumentProps } from "./PlanStreamingDocument.js";
 export {
-  SessionInspector,
-  useSessionInspector,
-  buildVisibleTabs,
-  SetupTab,
-} from "./inspector";
+  PLAN_DOCUMENT_ENTRY_ID,
+  PLAN_DOCUMENT_PATH,
+} from "./plan-document.js";
+
+// Selection types (for platform builders composing their own Inspect facet)
+export type { SelectedThreadItem } from "../internal/store/selection-store.js";
+
+// Session facet components — the panel's rail views (Config et al.), also
+// independently importable (DD-003).
+export { SetupTab } from "./facets/index.js";
 export type {
-  SessionInspectorProps,
-  SessionInspectorTabId,
-  UseSessionInspectorOptions,
-  UseSessionInspectorReturn,
   SetupTabProps,
   SetupTabMutationCallbacks,
-} from "./inspector";
+} from "./facets/index.js";
 
 // Session utilities (re-exported from @stigmer/sdk)
 export { PENDING_SUBJECT, resolvedSubject } from "@stigmer/sdk";

package/src/session/plan-document.ts

@@ -0,0 +1,19 @@
+// Identity of the session's plan tab in the workspace surface's editor group.
+//
+// Kept in its own module (not in PlanEditor.tsx) so behavior-only consumers —
+// useSessionPanel opens the tab, SessionViewer routes to it — depend on the
+// identity without pulling the component (and its markdown renderer) into
+// their module graph (DD-003 headless-first).
+
+import { virtualEntryId } from "../internal/store/index.js";
+import { PLAN_ARTIFACT_NAME } from "../library/detect-plan-artifact.js";
+
+/**
+ * Virtual entry id of the plan document tab. One tab per session — the host
+ * swaps WHICH plan the tab shows (latest editable, or a superseded plan
+ * read-only); the tab itself never multiplies.
+ */
+export const PLAN_DOCUMENT_ENTRY_ID = virtualEntryId("plan");
+
+/** The plan tab's path — doubles as its tab label, matching the artifact name. */
+export const PLAN_DOCUMENT_PATH = PLAN_ARTIFACT_NAME;

package/src/session/useAgentRefFromSession.ts

@@ -3,8 +3,8 @@
 import { useEffect, useState } from "react";
 import type { ResourceRef } from "@stigmer/sdk";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
 
 /** Return value of {@link useAgentRefFromSession}. */
 export interface UseAgentRefFromSessionReturn {