@stigmer/react 3.3.0 → 3.4.0

package/src/execution/__tests__/useCreateAgentExecution.test.tsx

@@ -137,6 +137,92 @@ describe("useCreateAgentExecution — one-call session bootstrap (sessionSpec)",
     expect(input.sessionSpec.executionTarget).toBeUndefined();
   });
 
+  it("passes the metadata map through on the bootstrap spec", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          metadata: { "acme/tenant": "t-1" },
+        },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toEqual({ "acme/tenant": "t-1" });
+  });
+
+  it("maps the typed sessionContext onto the reserved metadata key", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          sessionContext: "Role: platform admin",
+        },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toEqual({
+      "stigmer.ai/session-context": "Role: platform admin",
+    });
+  });
+
+  it("lets the typed sessionContext win over a raw entry under the reserved key", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          metadata: {
+            "acme/tenant": "t-1",
+            "stigmer.ai/session-context": "stale raw value",
+          },
+          sessionContext: "typed value",
+        },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toEqual({
+      "acme/tenant": "t-1",
+      "stigmer.ai/session-context": "typed value",
+    });
+  });
+
+  it("omits metadata entirely when neither field is provided", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: { agentInstanceId: "ain-1" },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toBeUndefined();
+  });
+
   it("returns the server-assigned session id from the bootstrap response", async () => {
     mockCreate.mockResolvedValueOnce({
       metadata: { id: "aex-1" },

package/src/execution/useCreateAgentExecution.ts

@@ -2,12 +2,13 @@
 
 import { useCallback, useState } from "react";
 import type { JsonObject } from "@bufbuild/protobuf";
-import type {
-  AttachmentInput,
-  EnvVarInput,
-  McpServerUsageInput,
-  ResourceRef,
-  WorkspaceEntryInput,
+import {
+  mergeSessionContext,
+  type AttachmentInput,
+  type EnvVarInput,
+  type McpServerUsageInput,
+  type ResourceRef,
+  type WorkspaceEntryInput,
 } from "@stigmer/sdk";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
@@ -41,6 +42,36 @@ export interface BootstrapSessionSpec {
   readonly mcpServerUsages?: McpServerUsageInput[];
   /** Skill references to enable for executions in this session. */
   readonly skillRefs?: ResourceRef[];
+  /**
+   * 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} 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 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;
   /** Execution harness. Immutable after the first execution runs. */
   readonly harness?: HarnessOption;
   /** Where session activities execute. Immutable after the first execution runs. */
@@ -293,6 +324,10 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
               workspaceEntries: input.sessionSpec.workspaceEntries,
               mcpServerUsages: input.sessionSpec.mcpServerUsages,
               skillRefs: input.sessionSpec.skillRefs,
+              metadata: mergeSessionContext(
+                input.sessionSpec.metadata,
+                input.sessionSpec.sessionContext,
+              ),
               harness: input.sessionSpec.harness
                 ? toProtoHarness(input.sessionSpec.harness)
                 : undefined,

package/src/index.ts

@@ -909,21 +909,16 @@ export type {
   OrgSwitcherProps,
 } from "./organization/index.js";
 
-// Billing — data hooks, behavior hooks, styled components, catalog, and formatting utilities
+// Billing — customer-facing data hooks, behavior hooks, styled components,
+// catalog, and formatting utilities
 export {
   useBillingAccount,
   useCreditLedger,
   useBillingUsageReport,
   useCustomerModelPricing,
-  usePricingGovernance,
-  useModelPricingBaselines,
-  useModelGovernanceView,
   useCreateCheckoutSession,
   useCreateBillingPortalSession,
   useSetAutoRechargeConfig,
-  useDecidePricingOverride,
-  useUpsertModelPricingBaseline,
-  useRetireModelPricingBaseline,
   BillingSection,
   CreditBalanceCard,
   PaymentMethodCard,
@@ -931,9 +926,6 @@ export {
   CreditPackGrid,
   CreditLedgerTable,
   LowBalanceBanner,
-  PricingGovernancePanel,
-  ModelCatalogPanel,
-  PricingGovernanceConsole,
   CREDIT_PACKS,
   formatPackPrice,
   formatCreditCount,
@@ -950,23 +942,11 @@ export type {
   UseCreditLedgerOptions,
   UseBillingUsageReportReturn,
   UseCustomerModelPricingReturn,
-  UsePricingGovernanceReturn,
-  UseModelPricingBaselinesOptions,
-  UseModelPricingBaselinesReturn,
-  GovernanceFlow,
-  ModelGovernanceRow,
-  UseModelGovernanceViewReturn,
   CreateCheckoutSessionInput,
   UseCreateCheckoutSessionReturn,
   UseCreateBillingPortalSessionReturn,
   SetAutoRechargeConfigInput,
   UseSetAutoRechargeConfigReturn,
-  DecidePricingOverrideInput,
-  UseDecidePricingOverrideReturn,
-  UpsertModelPricingBaselineInput,
-  UseUpsertModelPricingBaselineReturn,
-  RetireModelPricingBaselineInput,
-  UseRetireModelPricingBaselineReturn,
   BillingSectionProps,
   CreditBalanceCardProps,
   PaymentMethodCardProps,
@@ -974,12 +954,40 @@ export type {
   CreditPackGridProps,
   CreditLedgerTableProps,
   LowBalanceBannerProps,
+  CreditPackInfo,
+} from "./billing/index.js";
+
+// Pricing governance — platform-operator authoring of the model registry
+// baseline and pricing-override sign-offs (gated on can_manage_model_pricing)
+export {
+  usePricingGovernance,
+  useModelPricingBaselines,
+  useModelGovernanceView,
+  useDecidePricingOverride,
+  useUpsertModelPricingBaseline,
+  useRetireModelPricingBaseline,
+  PricingGovernancePanel,
+  ModelCatalogPanel,
+  PricingGovernanceConsole,
+} from "./pricing-governance/index.js";
+export type {
+  UsePricingGovernanceReturn,
+  UseModelPricingBaselinesOptions,
+  UseModelPricingBaselinesReturn,
+  GovernanceFlow,
+  ModelGovernanceRow,
+  UseModelGovernanceViewReturn,
+  DecidePricingOverrideInput,
+  UseDecidePricingOverrideReturn,
+  UpsertModelPricingBaselineInput,
+  UseUpsertModelPricingBaselineReturn,
+  RetireModelPricingBaselineInput,
+  UseRetireModelPricingBaselineReturn,
   PricingGovernancePanelProps,
   ModelCatalogPanelProps,
   PricingGovernanceConsoleProps,
   PricingGovernanceTab,
-  CreditPackInfo,
-} from "./billing/index.js";
+} from "./pricing-governance/index.js";
 
 // Cursor accounts — platform-operator management of managed Cursor teams
 // (admin keys, member execution keys, org assignments, roster/spend)

package/src/{billing → internal}/form-primitives.tsx

@@ -3,12 +3,12 @@
 import { cn } from "@stigmer/theme";
 
 // ---------------------------------------------------------------------------
-// Shared form primitives for the operator pricing surfaces (BaselineEditor,
-// RetireConfirm, the console's search inputs). Internal — not exported
-// from the billing barrel.
+// Shared form primitives for the operator consoles (pricing-governance
+// editors and search inputs, cursor-accounts editor and key forms).
+// Internal — never exported from the package barrel.
 // ---------------------------------------------------------------------------
 
-/** Standard text-input styling for the pricing surfaces. */
+/** Standard text-input styling for the operator consoles. */
 export const INPUT_CLASSES = cn(
   "w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground",
   "placeholder:text-muted-foreground",
@@ -38,31 +38,3 @@ export function Field({
     </label>
   );
 }
-
-/** Dollar-rate input field (decimal keypad, "$ per million tokens"). */
-export function RateField({
-  label,
-  value,
-  placeholder,
-  disabled,
-  onChange,
-}: {
-  readonly label: string;
-  readonly value: string;
-  readonly placeholder?: string;
-  readonly disabled: boolean;
-  readonly onChange: (value: string) => void;
-}) {
-  return (
-    <Field label={label}>
-      <input
-        className={INPUT_CLASSES}
-        inputMode="decimal"
-        value={value}
-        onChange={(e) => onChange(e.target.value)}
-        placeholder={placeholder ?? "0.00"}
-        disabled={disabled}
-      />
-    </Field>
-  );
-}

package/src/{billing → pricing-governance}/BaselineEditor.tsx

@@ -10,7 +10,7 @@ import {
   type ModelPricingBaseline,
 } from "@stigmer/protos/ai/stigmer/billing/v1/model_pricing_baseline_pb";
 import { Button } from "../button/index.js";
-import { Field, INPUT_CLASSES, RateField } from "./form-primitives.js";
+import { Field, INPUT_CLASSES } from "../internal/form-primitives.js";
 import {
   ZERO,
   dollarsToMicros,
@@ -23,10 +23,43 @@ import {
 // explicit old→new rate confirmation step (a billing-critical edit is never
 // submitted without the operator seeing exactly which rates move).
 //
-// Internal to the billing module: rendered by PricingGovernanceConsole and
-// ModelCatalogPanel, never exported from the barrel.
+// Internal to the pricing-governance module: rendered by
+// PricingGovernanceConsole and ModelCatalogPanel, never exported from the
+// barrel.
 // ---------------------------------------------------------------------------
 
+/**
+ * Dollar-rate input field (decimal keypad, "$ per million tokens").
+ * File-local: this is the editor's own composition of the shared form
+ * primitives, used nowhere else.
+ */
+function RateField({
+  label,
+  value,
+  placeholder,
+  disabled,
+  onChange,
+}: {
+  readonly label: string;
+  readonly value: string;
+  readonly placeholder?: string;
+  readonly disabled: boolean;
+  readonly onChange: (value: string) => void;
+}) {
+  return (
+    <Field label={label}>
+      <input
+        className={INPUT_CLASSES}
+        inputMode="decimal"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder ?? "0.00"}
+        disabled={disabled}
+      />
+    </Field>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Form model — strings while editing, converted + validated on submit.
 // Validation mirrors the protovalidate rules on ModelPricingBaseline so

package/src/{billing → pricing-governance}/PricingGovernanceConsole.tsx

@@ -11,7 +11,7 @@ import { RetireConfirm } from "./RetireConfirm.js";
 import { ModelGovernanceDetail } from "./ModelGovernanceDetail.js";
 import { OperatorAccessNotice } from "./OperatorAccessNotice.js";
 import { GovernanceBadge, PendingOverrideCard, RateCell } from "./governance-primitives.js";
-import { INPUT_CLASSES } from "./form-primitives.js";
+import { INPUT_CLASSES } from "../internal/form-primitives.js";
 import { ZERO } from "./pricing-format.js";
 import { useDecidePricingOverride } from "./useDecidePricingOverride.js";
 import { useRetireModelPricingBaseline } from "./useRetireModelPricingBaseline.js";

package/src/{billing → pricing-governance}/RetireConfirm.tsx

@@ -4,7 +4,7 @@ import { useState } from "react";
 import { getUserMessage } from "@stigmer/sdk";
 import type { ModelPricingBaseline } from "@stigmer/protos/ai/stigmer/billing/v1/model_pricing_baseline_pb";
 import { Button } from "../button/index.js";
-import { INPUT_CLASSES } from "./form-primitives.js";
+import { INPUT_CLASSES } from "../internal/form-primitives.js";
 
 // ---------------------------------------------------------------------------
 // RetireConfirm — typed confirmation for retiring a catalog entry (a

package/src/pricing-governance/index.ts

@@ -0,0 +1,50 @@
+// Pricing governance — the platform-operator surface for the model
+// registry baseline and the reconciliation-driven pricing feedback loop.
+// Every export here is gated on `can_manage_model_pricing` on
+// `platform:stigmer`; nothing in this module is customer-facing (customer
+// billing lives in ../billing). The module boundary is deliberate: the
+// docs generator excludes operator-only domains wholesale, so operator
+// exports must never be mixed into customer modules.
+
+// Data hooks
+export { usePricingGovernance } from "./usePricingGovernance.js";
+export type { UsePricingGovernanceReturn } from "./usePricingGovernance.js";
+export { useModelPricingBaselines } from "./useModelPricingBaselines.js";
+export type {
+  UseModelPricingBaselinesOptions,
+  UseModelPricingBaselinesReturn,
+} from "./useModelPricingBaselines.js";
+export { useModelGovernanceView } from "./useModelGovernanceView.js";
+export type {
+  GovernanceFlow,
+  ModelGovernanceRow,
+  UseModelGovernanceViewReturn,
+} from "./useModelGovernanceView.js";
+
+// Behavior hooks
+export { useDecidePricingOverride } from "./useDecidePricingOverride.js";
+export type {
+  DecidePricingOverrideInput,
+  UseDecidePricingOverrideReturn,
+} from "./useDecidePricingOverride.js";
+export { useUpsertModelPricingBaseline } from "./useUpsertModelPricingBaseline.js";
+export type {
+  UpsertModelPricingBaselineInput,
+  UseUpsertModelPricingBaselineReturn,
+} from "./useUpsertModelPricingBaseline.js";
+export { useRetireModelPricingBaseline } from "./useRetireModelPricingBaseline.js";
+export type {
+  RetireModelPricingBaselineInput,
+  UseRetireModelPricingBaselineReturn,
+} from "./useRetireModelPricingBaseline.js";
+
+// Styled components
+export { PricingGovernancePanel } from "./PricingGovernancePanel.js";
+export type { PricingGovernancePanelProps } from "./PricingGovernancePanel.js";
+export { ModelCatalogPanel } from "./ModelCatalogPanel.js";
+export type { ModelCatalogPanelProps } from "./ModelCatalogPanel.js";
+export { PricingGovernanceConsole } from "./PricingGovernanceConsole.js";
+export type {
+  PricingGovernanceConsoleProps,
+  PricingGovernanceTab,
+} from "./PricingGovernanceConsole.js";

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/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