@stigmer/react 3.3.0 → 3.4.0

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>
  *   );
  * }