@stigmer/react 3.2.3 → 3.4.0

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/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/useEditSessionPrep.ts

@@ -7,7 +7,7 @@ import { useStigmer } from "../hooks.js";
 import { useAgent } from "../agent/index.js";
 import { useMcpServer } from "../mcp-server/index.js";
 import { useSkill } from "../skill/index.js";
-import { serializeAgentYaml, serializeMcpServerYaml } from "../library/index.js";
+import { serializeManifest } from "@stigmer/sdk";
 import type { DraftResourceType } from "./draft.js";
 
 /** Return value of {@link useEditSessionPrep}. */
@@ -64,7 +64,7 @@ export function useEditSessionPrep(
     if (draftType === "agent" && editAgent) {
       built.current = true;
       try {
-        const yaml = serializeAgentYaml(editAgent);
+        const yaml = serializeManifest(editAgent);
         const slug = editAgent.metadata?.slug ?? "agent";
         setFiles([new File([yaml], `${slug}.yaml`, { type: "text/yaml" })]);
       } catch {
@@ -75,7 +75,7 @@ export function useEditSessionPrep(
     if (draftType === "mcp-server" && editMcpServer) {
       built.current = true;
       try {
-        const yaml = serializeMcpServerYaml(editMcpServer);
+        const yaml = serializeManifest(editMcpServer);
         const slug = editMcpServer.metadata?.slug ?? "mcp-server";
         setFiles([new File([yaml], `${slug}.yaml`, { type: "text/yaml" })]);
       } catch {

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/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/settings/__tests__/useSettingsNavGroups.test.tsx

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { useRef, useState } from "react";
+import { SETTINGS_NAV_GROUPS, PLATFORM_SETTINGS_NAV_GROUP } from "../settings-nav";
+import { useSettingsNavGroups } from "../useSettingsNavGroups";
+
+// Drive the nav gate through the permission hook. The fail-closed
+// semantics themselves are covered by useCheckPermission's own suite —
+// here we assert the nav hook's per-item composition of the verdicts.
+// Verdicts are keyed by relation so each platform permission can be
+// granted independently.
+let verdicts: Record<string, boolean> = {};
+let checkedRelations: string[] = [];
+let lastCheckArgs: readonly unknown[] = [];
+
+vi.mock("../../iam-policy/useCheckPermission", () => ({
+  useCheckPermission: (
+    ...args: [unknown, string, { fail?: string } | undefined]
+  ) => {
+    lastCheckArgs = args;
+    checkedRelations.push(args[1]);
+    return { allowed: verdicts[args[1]] === true, isLoading: false, error: null };
+  },
+}));
+
+afterEach(() => {
+  cleanup();
+  verdicts = {};
+  checkedRelations = [];
+});
+
+function GroupsProbe() {
+  const groups = useSettingsNavGroups();
+  const platform = groups.find((g) => g.label === PLATFORM_SETTINGS_NAV_GROUP.label);
+  return (
+    <div
+      data-testid="groups"
+      data-labels={groups.map((g) => g.label).join(",")}
+      data-platform-items={platform?.items.map((i) => i.label).join(",") ?? ""}
+    />
+  );
+}
+
+const BASE_LABELS = SETTINGS_NAV_GROUPS.map((g) => g.label).join(",");
+
+describe("useSettingsNavGroups", () => {
+  it("appends the full Platform group when the operator holds every platform permission", () => {
+    verdicts = {
+      can_manage_model_pricing: true,
+      can_manage_cursor_accounts: true,
+    };
+    render(<GroupsProbe />);
+
+    const el = screen.getByTestId("groups");
+    expect(el.getAttribute("data-labels")).toBe(
+      `${BASE_LABELS},${PLATFORM_SETTINGS_NAV_GROUP.label}`,
+    );
+    expect(el.getAttribute("data-platform-items")).toBe(
+      "Pricing Governance,Cursor Accounts",
+    );
+  });
+
+  it("filters per item: pricing-only operator sees only Pricing Governance", () => {
+    verdicts = { can_manage_model_pricing: true };
+    render(<GroupsProbe />);
+
+    expect(screen.getByTestId("groups").getAttribute("data-platform-items")).toBe(
+      "Pricing Governance",
+    );
+  });
+
+  it("filters per item: cursor-accounts-only operator sees only Cursor Accounts", () => {
+    verdicts = { can_manage_cursor_accounts: true };
+    render(<GroupsProbe />);
+
+    expect(screen.getByTestId("groups").getAttribute("data-platform-items")).toBe(
+      "Cursor Accounts",
+    );
+  });
+
+  it("returns exactly the base groups when not authorized", () => {
+    function IdentityProbe() {
+      const groups = useSettingsNavGroups();
+      return (
+        <div
+          data-testid="identity"
+          data-is-base={String(groups === SETTINGS_NAV_GROUPS)}
+        />
+      );
+    }
+    render(<IdentityProbe />);
+
+    // Not just equivalent — the same array, no needless copy.
+    expect(screen.getByTestId("identity").getAttribute("data-is-base")).toBe("true");
+  });
+
+  it("checks every declared platform permission on platform:stigmer, fail-closed", () => {
+    render(<GroupsProbe />);
+
+    // Exhaustiveness guard: every requiredPermission declared on the
+    // platform group must have a corresponding hook check — a new
+    // platform surface that forgets to add its check fails here.
+    const declared = PLATFORM_SETTINGS_NAV_GROUP.items.map(
+      (item) => item.requiredPermission,
+    );
+    for (const permission of declared) {
+      expect(permission, "platform items must declare requiredPermission").toBeDefined();
+      expect(checkedRelations).toContain(permission);
+    }
+    expect(lastCheckArgs[0]).toEqual({ kind: "platform", id: "stigmer" });
+    expect(lastCheckArgs[2]).toEqual({ fail: "closed" });
+  });
+
+  it("keeps the array reference stable across re-renders", () => {
+    verdicts = {
+      can_manage_model_pricing: true,
+      can_manage_cursor_accounts: true,
+    };
+
+    function StabilityProbe() {
+      const groups = useSettingsNavGroups();
+      const first = useRef(groups);
+      const [, force] = useState(0);
+      return (
+        <button
+          data-testid="stability"
+          data-stable={String(first.current === groups)}
+          onClick={() => force((n) => n + 1)}
+        />
+      );
+    }
+
+    render(<StabilityProbe />);
+    const el = screen.getByTestId("stability");
+    fireEvent.click(el);
+    expect(el.getAttribute("data-stable")).toBe("true");
+  });
+});

package/src/settings/index.ts

@@ -1,5 +1,9 @@
-export { SETTINGS_NAV_GROUPS } from "./settings-nav.js";
+export {
+  SETTINGS_NAV_GROUPS,
+  PLATFORM_SETTINGS_NAV_GROUP,
+} from "./settings-nav.js";
 export type { SettingsNavItem, SettingsNavGroup } from "./settings-nav.js";
+export { useSettingsNavGroups } from "./useSettingsNavGroups.js";
 
 export { ApiKeysSection } from "./ApiKeysSection.js";
 export { BillingSection } from "./BillingSection.js";

package/src/settings/settings-nav.ts

@@ -8,7 +8,9 @@ import {
   KeyRound,
   Link,
   MessageSquare,
+  MousePointerClick,
   Plug,
+  Scale,
   ShieldCheck,
   Users,
 } from "lucide-react";
@@ -24,6 +26,14 @@ export interface SettingsNavItem {
     /** Optional CSS class name applied to the icon. */
     className?: string;
   }>;
+  /**
+   * Platform-level permission (on `platform:stigmer`) required for this
+   * entry to appear. Only meaningful inside
+   * {@link PLATFORM_SETTINGS_NAV_GROUP} — items in the base groups are
+   * visible to every signed-in user and leave this unset.
+   * {@link useSettingsNavGroups} checks it fail-closed.
+   */
+  readonly requiredPermission?: string;
 }
 
 /** Grouping model used to render settings navigation sections. */
@@ -82,3 +92,36 @@ export const SETTINGS_NAV_GROUPS: readonly SettingsNavGroup[] = [
     ],
   },
 ];
+
+/**
+ * Stigmer-internal platform-operator navigation group.
+ *
+ * Deliberately NOT part of {@link SETTINGS_NAV_GROUPS}: that constant
+ * means "groups every signed-in user sees", and its members must never
+ * change based on who is looking. This group is appended for platform
+ * operators only — use {@link useSettingsNavGroups} to get the
+ * permission-aware list instead of composing the two by hand.
+ *
+ * Every item here declares its `requiredPermission`; the hook filters
+ * per item (fail-closed), so an operator holding one platform permission
+ * but not another sees exactly their slice of this group.
+ */
+export const PLATFORM_SETTINGS_NAV_GROUP: SettingsNavGroup = {
+  label: "Platform",
+  description:
+    "Stigmer-internal operations. Visible to platform operators only.",
+  items: [
+    {
+      href: "/settings/pricing-governance",
+      label: "Pricing Governance",
+      icon: Scale,
+      requiredPermission: "can_manage_model_pricing",
+    },
+    {
+      href: "/settings/cursor-accounts",
+      label: "Cursor Accounts",
+      icon: MousePointerClick,
+      requiredPermission: "can_manage_cursor_accounts",
+    },
+  ],
+};

package/src/settings/useSettingsNavGroups.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useMemo } from "react";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import {
+  PLATFORM_SETTINGS_NAV_GROUP,
+  SETTINGS_NAV_GROUPS,
+  type SettingsNavGroup,
+} from "./settings-nav.js";
+
+/**
+ * The `platform` singleton — platform-level permissions are always
+ * checked against this one resource (mirrors the server-side
+ * `resource_id = "stigmer"` RPC config).
+ */
+const PLATFORM_RESOURCE = { kind: "platform", id: "stigmer" } as const;
+
+/**
+ * Permission-aware settings navigation: {@link SETTINGS_NAV_GROUPS}
+ * for everyone, plus the {@link PLATFORM_SETTINGS_NAV_GROUP} items the
+ * caller's platform permissions unlock (per-item `requiredPermission`,
+ * checked against `platform:stigmer`). The group appears when at least
+ * one of its items is visible.
+ *
+ * The checks run fail-closed — the opposite of the `useCheckPermission`
+ * default — because navigation is *discoverability*, not *capability*:
+ * an action gate can safely fail open (the server re-checks every
+ * request), but an operator-only nav entry must not appear while the
+ * check is loading, when it errors, or on deployments where the IAM
+ * service (and the surface it points to) does not exist.
+ *
+ * Implementation note: hooks must be called unconditionally, so each
+ * distinct platform permission gets its own static check below. When a
+ * new platform surface adds a new permission, add its check to
+ * PLATFORM_PERMISSION_CHECKS' shape here — the exhaustiveness guard in
+ * the tests catches a forgotten one.
+ *
+ * @example
+ * ```tsx
+ * const groups = useSettingsNavGroups();
+ * return groups.map((group) => <NavGroup key={group.label} group={group} />);
+ * ```
+ */
+export function useSettingsNavGroups(): readonly SettingsNavGroup[] {
+  const pricing = useCheckPermission(
+    PLATFORM_RESOURCE,
+    "can_manage_model_pricing",
+    { fail: "closed" },
+  );
+  const cursorAccounts = useCheckPermission(
+    PLATFORM_RESOURCE,
+    "can_manage_cursor_accounts",
+    { fail: "closed" },
+  );
+
+  const pricingAllowed = pricing.allowed;
+  const cursorAccountsAllowed = cursorAccounts.allowed;
+
+  return useMemo(() => {
+    const verdicts: Record<string, boolean> = {
+      can_manage_model_pricing: pricingAllowed,
+      can_manage_cursor_accounts: cursorAccountsAllowed,
+    };
+
+    const visibleItems = PLATFORM_SETTINGS_NAV_GROUP.items.filter(
+      // Fail closed on both axes: an item with no declared permission or
+      // with a permission this hook does not check yet stays hidden.
+      (item) =>
+        item.requiredPermission !== undefined &&
+        verdicts[item.requiredPermission] === true,
+    );
+
+    if (visibleItems.length === 0) {
+      return SETTINGS_NAV_GROUPS;
+    }
+    return [
+      ...SETTINGS_NAV_GROUPS,
+      { ...PLATFORM_SETTINGS_NAV_GROUP, items: visibleItems },
+    ];
+  }, [pricingAllowed, cursorAccountsAllowed]);
+}