@stigmer/react 3.3.0 → 3.4.1

package/src/session/SessionViewerLayout.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import { ResizableSplit } from "../internal/ResizableSplit.js";
+
+/** Props for {@link SessionViewerLayout}. */
+export interface SessionViewerLayoutProps {
+  /**
+   * The conversation column — the layout's primary (left) pane. Stays
+   * mounted at a stable tree position across every panel open/close, so
+   * streaming and scroll state survive the toggle.
+   */
+  readonly conversation: ReactNode;
+  /**
+   * The session panel content, or `null` while the panel is collapsed.
+   * This is the single source of truth for the collapsed state: passing
+   * `null` collapses the split (the conversation fills the row) and hides
+   * the drag separator; passing content expands the panel into the
+   * flexible region. Hosts derive it from their panel controller, e.g.
+   * `panel.isOpen ? <WorkspaceSurface … /> : null`.
+   */
+  readonly panel: ReactNode | null;
+  /**
+   * The panel's toggle chip, rendered in the layout's top-right corner
+   * (typically the session panel chip, {@link PanelChip}). Omit it to
+   * render no toggle — how hosts express audiences that must never open
+   * the panel (the guest case in {@link SessionViewer} and
+   * {@link NewSessionViewer}).
+   */
+  readonly chip?: ReactNode;
+  /**
+   * Host-injected header actions, rendered beside the chip in the
+   * top-right corner (slot injection, as {@link SessionViewerProps.headerActions}).
+   */
+  readonly headerActions?: ReactNode;
+  /**
+   * `localStorage` key persisting the chat pane's drag-resized width
+   * across sessions. Each host passes its own key so the two shipped
+   * viewers keep distinct widths. **Omit it in deterministic hosts**
+   * (documentation embeds, video export): with no key the width always
+   * starts at the default, so every render of the same input is
+   * pixel-identical instead of depending on previously persisted state.
+   */
+  readonly splitStorageKey?: string;
+  /**
+   * Whether the conversation pane collapses below the `lg` breakpoint
+   * while the panel is open, leaving the panel full-width — the shipped
+   * console behavior on narrow windows.
+   *
+   * Pass `false` in fixed-canvas hosts, where the media query is
+   * meaningless or actively wrong: a documentation embed renders in an
+   * iframe whose viewport is the docs column (below `lg` on most pages),
+   * so the default would hide the conversation on exactly the beats that
+   * open the panel.
+   *
+   * @default true
+   */
+  readonly responsive?: boolean;
+  /**
+   * Accessible label for the split's drag separator. Name the pane being
+   * resized in the host's vocabulary (the session viewer's chat pane vs
+   * the launcher's composer pane).
+   *
+   * @default "Resize chat panel"
+   */
+  readonly resizeAriaLabel?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * The one conversation-plus-panel frame every session viewer shares —
+ * {@link SessionViewer} and {@link NewSessionViewer} both render it, so the
+ * two surfaces cannot drift apart (their behave-identically contract), and
+ * platform builders composing a custom session surface from
+ * {@link WorkspaceSurface}, {@link PanelChip}, and the session facets get
+ * the same geometry the shipped console uses.
+ *
+ * The layout owns exactly three things:
+ *
+ * - **The top-right control corner** — the host's `headerActions` beside
+ *   the panel toggle `chip`, absolutely positioned over the conversation.
+ * - **The split geometry** — chat fills the row while the panel is
+ *   collapsed; opening makes the chat the fixed, drag-resizable pane
+ *   (420px default, 320–640px) and hands the flexible region to the panel.
+ * - **The collapse mechanics** — collapse goes through the split's
+ *   `collapsedPane` (CSS, not conditional structure), so the conversation
+ *   is always the same first child and an open/close toggle never
+ *   remounts it.
+ *
+ * Everything rendered inside the panes belongs to the host: the layout
+ * takes opaque `ReactNode`s and never inspects them.
+ */
+export function SessionViewerLayout({
+  conversation,
+  panel,
+  chip,
+  headerActions,
+  splitStorageKey,
+  responsive = true,
+  resizeAriaLabel = "Resize chat panel",
+  className,
+}: SessionViewerLayoutProps) {
+  const isPanelOpen = panel != null;
+
+  return (
+    <div className={cn("relative flex h-full w-full flex-col", className)}>
+      {(headerActions != null || chip != null) && (
+        <div className="absolute top-2 right-6 z-10 flex items-center gap-2">
+          {headerActions}
+          {chip}
+        </div>
+      )}
+
+      <ResizableSplit
+        resizablePane="primary"
+        collapsedPane={isPanelOpen ? "none" : "secondary"}
+        defaultSize={420}
+        minSize={320}
+        maxSize={640}
+        storageKey={splitStorageKey}
+        responsiveCollapse={responsive && isPanelOpen ? "primary" : "none"}
+        ariaLabel={resizeAriaLabel}
+        className="min-h-0 flex-1"
+        primary={conversation}
+        secondary={panel}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { SessionViewerLayout } from "../SessionViewerLayout";
+
+// ---------------------------------------------------------------------------
+// The one conversation-plus-panel frame both shipped viewers render
+// (SessionViewer + NewSessionViewer), so the two surfaces cannot drift.
+// The contract under test:
+//   - `panel` is the single source of truth for collapsed state
+//   - the conversation never remounts across an open/close toggle
+//   - `responsive={false}` disables the below-`lg` conversation collapse
+//     (fixed-canvas hosts: docs embeds, video export)
+//   - no `splitStorageKey` means no localStorage read (deterministic hosts)
+// ---------------------------------------------------------------------------
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  localStorage.clear();
+});
+
+function conversation() {
+  return <div data-testid="conversation">chat</div>;
+}
+
+function panel() {
+  return <div data-testid="panel">panel</div>;
+}
+
+describe("SessionViewerLayout", () => {
+  it("collapsed (panel null): conversation renders, panel absent, no separator exposed", () => {
+    render(<SessionViewerLayout conversation={conversation()} panel={null} />);
+    expect(screen.getByTestId("conversation").textContent).toBe("chat");
+    expect(screen.queryByTestId("panel")).toBeNull();
+    // The drag separator is CSS-hidden and aria-hidden while collapsed.
+    expect(screen.queryByRole("separator")).toBeNull();
+  });
+
+  it("open (panel provided): panel renders and the separator is operable", () => {
+    render(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    expect(screen.getByTestId("panel").textContent).toBe("panel");
+    const separator = screen.getByRole("separator", { name: "Resize chat panel" });
+    expect(separator.getAttribute("tabindex")).toBe("0");
+  });
+
+  it("resizeAriaLabel names the separator in the host's vocabulary", () => {
+    render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={panel()}
+        resizeAriaLabel="Resize composer panel"
+      />,
+    );
+    expect(
+      screen.queryByRole("separator", { name: "Resize composer panel" }),
+    ).not.toBeNull();
+  });
+
+  it("never remounts the conversation across an open/close toggle", () => {
+    const { rerender } = render(
+      <SessionViewerLayout conversation={conversation()} panel={null} />,
+    );
+    const node = screen.getByTestId("conversation");
+
+    rerender(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    expect(screen.getByTestId("conversation")).toBe(node);
+
+    rerender(<SessionViewerLayout conversation={conversation()} panel={null} />);
+    expect(screen.getByTestId("conversation")).toBe(node);
+  });
+
+  it("open panel sizes the conversation pane at the shared default width", () => {
+    render(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    const pane = screen.getByTestId("conversation").parentElement!;
+    expect(pane.style.width).toBe("420px");
+  });
+
+  it("responsive (default): the open-panel conversation pane collapses below lg", () => {
+    const { container } = render(
+      <SessionViewerLayout conversation={conversation()} panel={panel()} />,
+    );
+    const pane = screen.getByTestId("conversation").parentElement!;
+    expect(pane.className).toContain("max-lg:hidden");
+    // The separator hides with it, so the panel is the full row below lg.
+    expect(container.querySelectorAll('[class*="max-lg:hidden"]').length).toBe(2);
+  });
+
+  it("responsive={false}: no below-lg collapse anywhere (fixed-canvas hosts)", () => {
+    const { container } = render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={panel()}
+        responsive={false}
+      />,
+    );
+    expect(container.querySelector('[class*="max-lg:hidden"]')).toBeNull();
+  });
+
+  it("reads no localStorage without a splitStorageKey (deterministic hosts)", () => {
+    const getItem = vi.spyOn(Storage.prototype, "getItem");
+    render(<SessionViewerLayout conversation={conversation()} panel={panel()} />);
+    expect(getItem).not.toHaveBeenCalled();
+  });
+
+  it("seeds the pane width from the host's splitStorageKey when given", () => {
+    localStorage.setItem("stgm-test-chat-width", "512");
+    render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={panel()}
+        splitStorageKey="stgm-test-chat-width"
+      />,
+    );
+    const pane = screen.getByTestId("conversation").parentElement!;
+    expect(pane.style.width).toBe("512px");
+  });
+
+  it("renders headerActions beside the chip in the top-right corner", () => {
+    render(
+      <SessionViewerLayout
+        conversation={conversation()}
+        panel={null}
+        headerActions={<button type="button">Share</button>}
+        chip={<button type="button">Toggle panel</button>}
+      />,
+    );
+    const actions = screen.getByRole("button", { name: "Share" });
+    const chip = screen.getByRole("button", { name: "Toggle panel" });
+    expect(actions.parentElement).toBe(chip.parentElement);
+  });
+
+  it("renders no control corner when both chip and headerActions are omitted", () => {
+    const { container } = render(
+      <SessionViewerLayout conversation={conversation()} panel={null} />,
+    );
+    // The corner is the only `top-2`-positioned element in the layout (the
+    // separator's inner hit target is also `absolute`, so match the corner).
+    expect(container.querySelector('[class*="top-2"]')).toBeNull();
+  });
+});

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

@@ -193,6 +193,100 @@ describe("useCreateSession", () => {
     expect(callArg.executionTarget).toBeUndefined();
   });
 
+  describe("session metadata and sessionContext", () => {
+    it("passes the metadata map through to stigmer.session.create()", async () => {
+      const create = vi.fn().mockResolvedValue({ metadata: { id: "ses-md" } });
+      const client = createMockStigmer({ create });
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: wrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "ain-123",
+          metadata: { "acme/tenant": "t-1" },
+        });
+      });
+
+      expect(create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: { "acme/tenant": "t-1" },
+        }),
+      );
+    });
+
+    it("maps the typed sessionContext onto the reserved metadata key", async () => {
+      const create = vi.fn().mockResolvedValue({ metadata: { id: "ses-sc" } });
+      const client = createMockStigmer({ create });
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: wrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "ain-123",
+          sessionContext: "Role: platform admin",
+        });
+      });
+
+      expect(create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: { "stigmer.ai/session-context": "Role: platform admin" },
+        }),
+      );
+    });
+
+    it("lets the typed sessionContext win over a raw entry under the reserved key", async () => {
+      const create = vi.fn().mockResolvedValue({ metadata: { id: "ses-both" } });
+      const client = createMockStigmer({ create });
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: wrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({
+          org: "acme",
+          agentInstanceId: "ain-123",
+          metadata: {
+            "acme/tenant": "t-1",
+            "stigmer.ai/session-context": "stale raw value",
+          },
+          sessionContext: "typed value",
+        });
+      });
+
+      expect(create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: {
+            "acme/tenant": "t-1",
+            "stigmer.ai/session-context": "typed value",
+          },
+        }),
+      );
+    });
+
+    it("omits metadata entirely when neither field is provided", async () => {
+      const create = vi.fn().mockResolvedValue({ metadata: { id: "ses-none" } });
+      const client = createMockStigmer({ create });
+
+      const { result } = renderHook(() => useCreateSession(), {
+        wrapper: wrapper(client),
+      });
+
+      await act(async () => {
+        await result.current.create({ org: "acme", agentInstanceId: "ain-123" });
+      });
+
+      const callArg = create.mock.calls[0][0];
+      expect(callArg.metadata).toBeUndefined();
+    });
+  });
+
   it("clearError resets the error state", async () => {
     const create = vi.fn().mockRejectedValue(new Error("fail"));
     const client = createMockStigmer({ create });

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

@@ -334,6 +334,39 @@ describe("useNewSessionFlow", () => {
       expect(execInput.sessionSpec.harness).toBe("cursor");
     });
 
+    it("forwards metadata and sessionContext verbatim in the sessionSpec", async () => {
+      // The typed-wins merge onto the reserved key happens downstream in
+      // useCreateAgentExecution (covered by its own tests); the flow's job
+      // is faithful forwarding.
+      const opts = {
+        ...defaultOptions(),
+        metadata: { "acme/tenant": "t-1" },
+        sessionContext: "Role: platform admin",
+      };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.metadata).toEqual({ "acme/tenant": "t-1" });
+      expect(execInput.sessionSpec.sessionContext).toBe("Role: platform admin");
+    });
+
+    it("leaves metadata and sessionContext undefined when not provided", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.metadata).toBeUndefined();
+      expect(execInput.sessionSpec.sessionContext).toBeUndefined();
+    });
+
     it("calls onSessionCreated with the server-assigned session id", async () => {
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });

package/src/session/index.ts

@@ -109,6 +109,12 @@ export type { SessionViewerProps } from "./SessionViewer.js";
 export { NewSessionViewer } from "./NewSessionViewer.js";
 export type { NewSessionViewerProps } from "./NewSessionViewer.js";
 
+// SessionViewerLayout — the conversation-plus-panel frame both viewers
+// share, exported for platform builders composing a custom session surface
+// at the shipped console's geometry.
+export { SessionViewerLayout } from "./SessionViewerLayout.js";
+export type { SessionViewerLayoutProps } from "./SessionViewerLayout.js";
+
 // 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).
@@ -118,6 +124,14 @@ export type {
   UseSessionPanelOptions,
 } from "./useSessionPanel.js";
 
+// Session rail views — composes the session facets (Config / Changes /
+// Artifacts / Usage) as the panel's rail, with the console's own labels,
+// icons, badges, and contextual-visibility rules. Exported so custom
+// session surfaces inherit the rail by construction instead of
+// re-declaring it.
+export { useSessionRailViews } from "./useSessionRailViews.js";
+export type { UseSessionRailViewsOptions } from "./useSessionRailViews.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";

package/src/session/useCreateSession.ts

@@ -3,6 +3,7 @@
 import { useCallback, useState } from "react";
 import {
   PENDING_SUBJECT,
+  mergeSessionContext,
   type McpServerUsageInput,
   type ResourceRef,
   type WorkspaceEntryInput,
@@ -25,6 +26,34 @@ export interface SharedSessionFields {
   readonly mcpServerUsages?: McpServerUsageInput[];
   /** Skill references to enable for executions in this session. */
   readonly skillRefs?: ResourceRef[];
+  /**
+   * Custom key-value pairs stored on `SessionSpec.metadata`.
+   *
+   * A passthrough for embedder-owned keys (correlation IDs, tenant tags)
+   * and for platform-reserved `stigmer.ai/*` keys set explicitly. For the
+   * common case — standing user context injected into the agent's prompt —
+   * prefer the typed {@link sessionContext} field, which maps onto the
+   * reserved `stigmer.ai/session-context` key and wins over a raw entry
+   * under that key when both are provided.
+   */
+  readonly metadata?: Record<string, string>;
+  /**
+   * Standing, per-user context the agent receives on every turn but the
+   * conversation UI never renders — who the caller is, their experience
+   * level, their standing instructions (stigmer/stigmer#286).
+   *
+   * Stored on `SessionSpec.metadata` under `stigmer.ai/session-context`;
+   * the agent runner injects it into the system prompt as already-known
+   * background, so agents can greet the user by name and calibrate
+   * depth/defaults from the first turn without a visible context preamble.
+   *
+   * Personalization, not authorization: anyone who can create the session
+   * can set this (the same trust level as authoring the first message).
+   * Hidden from the conversation thread, not from the API — `session.get`
+   * returns it, so never put secrets here; secrets belong in `runtimeEnv`
+   * or Environment resources. Large values bloat every prompt.
+   */
+  readonly sessionContext?: string;
   /**
    * Execution harness for this session.
    *
@@ -172,6 +201,7 @@ export function useCreateSession(): UseCreateSessionReturn {
           workspaceEntries: input.workspaceEntries,
           mcpServerUsages: input.mcpServerUsages,
           skillRefs: input.skillRefs,
+          metadata: mergeSessionContext(input.metadata, input.sessionContext),
           agentInstanceId: resolvedInstanceId,
           harness: input.harness ? toProtoHarness(input.harness) : undefined,
           executionTarget: resolvedTarget

package/src/session/useNewSessionFlow.ts

@@ -111,6 +111,36 @@ export interface UseNewSessionFlowOptions {
    * @default "integrator"
    */
   readonly audience?: SessionAudience;
+  /**
+   * Custom key-value pairs stored on the created session's
+   * `SessionSpec.metadata`.
+   *
+   * A passthrough for embedder-owned keys (correlation IDs, tenant tags)
+   * and for platform-reserved `stigmer.ai/*` keys set explicitly. For the
+   * common case — standing user context injected into the agent's prompt —
+   * prefer the typed {@link sessionContext} option, which maps onto the
+   * reserved `stigmer.ai/session-context` key and wins over a raw entry
+   * under that key when both are provided.
+   */
+  readonly metadata?: Record<string, string>;
+  /**
+   * Standing, per-user context the agent receives on every turn but the
+   * conversation UI never renders — who the caller is, their experience
+   * level, their standing instructions (stigmer/stigmer#286).
+   *
+   * Stored on the created session's `SessionSpec.metadata` under
+   * `stigmer.ai/session-context`; the agent runner injects it into the
+   * system prompt as already-known background, so agents can greet the
+   * user by name and calibrate depth/defaults from the first turn without
+   * a visible context preamble.
+   *
+   * Personalization, not authorization: anyone who can create the session
+   * can set this (the same trust level as authoring the first message).
+   * Hidden from the conversation thread, not from the API — `session.get`
+   * returns it, so never put secrets here; secrets belong in `runtimeEnv`
+   * or Environment resources. Large values bloat every prompt.
+   */
+  readonly sessionContext?: string;
 }
 
 /** Return value of {@link useNewSessionFlow}. */
@@ -217,7 +247,15 @@ export interface UseNewSessionFlowReturn {
 export function useNewSessionFlow(
   options: UseNewSessionFlowOptions,
 ): UseNewSessionFlowReturn {
-  const { org, onSessionCreated, onError, getRuntimeEnv, defaultHarness } = options;
+  const {
+    org,
+    onSessionCreated,
+    onError,
+    getRuntimeEnv,
+    defaultHarness,
+    metadata,
+    sessionContext,
+  } = options;
   const isGuest = options.audience === "guest";
   const contextTarget = useExecutionTarget();
   const executionTarget = options.executionTarget ?? contextTarget;
@@ -336,6 +374,10 @@ export function useNewSessionFlow(
             : undefined,
           mcpServerUsages: mcpServerUsages.length > 0 ? mcpServerUsages : undefined,
           skillRefs: skillRefs.length > 0 ? skillRefs : undefined,
+          // The typed-wins merge happens downstream in useCreateAgentExecution;
+          // both fields are forwarded verbatim here.
+          metadata,
+          sessionContext,
           harness,
           executionTarget,
         };
@@ -440,6 +482,8 @@ export function useNewSessionFlow(
       workspace,
       mcpServerUsages,
       skillRefs,
+      metadata,
+      sessionContext,
       agentRef,
       resolution,
       defaultAgent,

package/src/session/useSessionRailViews.tsx

@@ -55,13 +55,13 @@ export interface UseSessionRailViewsOptions {
    * (a cloud session with git workspace entries). When `true` the Changes
    * facet is offered from the start — with an honest pre-push state — instead
    * of only materializing once a write-back exists, so "where does my work
-   * go?" always has an answer. See {@link ChangesTabProps.expectsWriteBack}.
+   * go?" always has an answer (the facet's `expectsWriteBack` prop).
    * @default false
    */
   readonly expectsWriteBack?: boolean;
   /**
    * Whether the session's latest execution is settled (terminal) — forwarded
-   * to the Changes facet's pre-push states. See {@link ChangesTabProps.isSettled}.
+   * to the Changes facet's pre-push states (its `isSettled` prop).
    * @default false
    */
   readonly changesSettled?: boolean;

package/src/session/useUpdateSession.ts

@@ -24,28 +24,47 @@ export interface UseUpdateSessionReturn {
  * {@link SessionInput} including the session's `name` and `org` (used
  * by the backend to identify the resource) and all spec fields.
  *
+ * **Full-replace semantics.** The backend replaces the entire spec with
+ * what you send — there is no field mask. Round-trip every spec field
+ * you do not intend to change, *including `metadata`*: an update built
+ * from a reconstructed partial spec silently wipes the fields it omits
+ * (workspace entries, MCP servers, and `stigmer.ai/*` metadata keys such
+ * as the embedder session context). To change only the subject, prefer
+ * the field-level `session.updateSubject()` RPC instead of this hook.
+ *
  * Typically composed into higher-level hooks like
- * {@link useSessionConversation} rather than used directly. Platform
- * builders who need direct session mutation can use this hook
- * standalone.
+ * {@link useSessionConversation} (whose update path round-trips the
+ * fetched spec) rather than used directly. Platform builders who need
+ * direct session mutation can use this hook standalone.
  *
  * @example
  * ```tsx
- * function RenameSession({ session }: { session: Session }) {
- *   const { update, isUpdating, error } = useUpdateSession();
+ * function TagSession({ session }: { session: Session }) {
+ *   const { update, isUpdating } = useUpdateSession();
  *
- *   async function handleRename(newSubject: string) {
+ *   async function handleTag() {
+ *     const spec = session.spec;
  *     await update({
  *       name: session.metadata!.name,
  *       org: session.metadata!.org,
- *       agentInstanceId: session.spec?.agentInstanceId,
- *       subject: newSubject,
+ *       // Full replace: carry over every fetched spec field...
+ *       agentInstanceId: spec?.agentInstanceId,
+ *       subject: spec?.subject,
+ *       harnessStateId: spec?.harnessStateId,
+ *       harness: spec?.harness,
+ *       cursorMode: spec?.cursorMode,
+ *       executionTarget: spec?.executionTarget,
+ *       // ...including the spec lists (workspaceEntries, mcpServerUsages,
+ *       // skillRefs), converted from the fetched proto exactly as
+ *       // useSessionConversation's update path does...
+ *       // ...then apply the one change on top of the carried metadata.
+ *       metadata: { ...spec?.metadata, "acme/reviewed": "true" },
  *     });
  *   }
  *
  *   return (
- *     <button onClick={() => handleRename("New subject")} disabled={isUpdating}>
- *       Rename
+ *     <button onClick={handleTag} disabled={isUpdating}>
+ *       Mark reviewed
  *     </button>
  *   );
  * }

package/src/skill/useSkillCount.ts

@@ -17,6 +17,8 @@ export interface UseSkillCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useSkillCount}. */