@stigmer/react 0.0.71 → 0.0.73

package/src/search/useResourceSearch.ts

@@ -4,6 +4,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import type { ListParams, ListResult } from "@stigmer/sdk";
 import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
 
+/** Shared options for resource search hooks (`useAgentSearch`, `useMcpServerSearch`, `useSkillSearch`). */
 export interface UseResourceSearchOptions {
   /** Maximum results per page. @default 30 */
   readonly pageSize?: number;
@@ -13,20 +14,27 @@ export interface UseResourceSearchOptions {
    * Controls search scope.
    *
    * - `"org"` — search only within the provided organization.
-   * - `"all"` — search all organizations the caller can access,
-   *   including public/platform resources from other orgs.
+   * - `"all"` — search within the provided organization plus public
+   *   resources from other organizations.
    *
    * @default "org"
    */
   readonly scope?: "org" | "all";
 }
 
+/** Shared return value for resource search hooks (`useAgentSearch`, `useMcpServerSearch`, `useSkillSearch`). */
 export interface UseResourceSearchReturn {
+  /** Matching resources from the most recent search. */
   readonly results: readonly SearchResult[];
+  /** `true` while a search request is in flight. */
   readonly isLoading: boolean;
+  /** Error message from the last failed search, or `null` when healthy. */
   readonly error: string | null;
+  /** Current search query text. */
   readonly query: string;
+  /** Update the search query (triggers a debounced re-search). */
   readonly setQuery: (query: string) => void;
+  /** Re-run the current search with the same parameters. */
   readonly refetch: () => void;
 }
 
@@ -72,9 +80,10 @@ export function useResourceSearch(
     setError(null);
 
     const params: ListParams = {
-      org: scope === "all" ? "" : org,
+      org,
       query: debouncedQuery || undefined,
       excludePublic: false,
+      crossOrgPublic: scope === "all",
       page: { num: 1, size: pageSize },
     };
 

package/src/session/group-sessions.ts

@@ -24,6 +24,29 @@ interface Bucket {
  * @param sessions - List of sessions to group (typically from `useSessionList`).
  * @param now - Reference time for grouping; defaults to the current time.
  *              Accepts an explicit value for deterministic testing.
+ *
+ * @example
+ * ```tsx
+ * function GroupedSessionList() {
+ *   const { sessions } = useSessionList();
+ *   const groups = groupSessionsByTime(sessions);
+ *
+ *   return (
+ *     <div>
+ *       {groups.map((group) => (
+ *         <section key={group.label}>
+ *           <h3>{group.label}</h3>
+ *           <ul>
+ *             {group.sessions.map((s) => (
+ *               <li key={s.metadata?.id}>{s.status?.subject}</li>
+ *             ))}
+ *           </ul>
+ *         </section>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function groupSessionsByTime(
   sessions: readonly Session[],

package/src/session/index.ts

@@ -1,5 +1,6 @@
 export { useCreateSession } from "./useCreateSession";
 export type {
+  SharedSessionFields,
   CreateSessionInput,
   CreateSessionResult,
   UseCreateSessionReturn,

package/src/session/useCreateSession.ts

@@ -10,11 +10,17 @@ import {
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
-interface SharedSessionFields {
+/** Shared fields present in both variants of {@link CreateSessionInput}. */
+export interface SharedSessionFields {
+  /** Organization slug for the new session. */
   readonly org: string;
+  /** Workspace source entries to attach to the session. */
   readonly workspaceEntries?: WorkspaceEntryInput[];
+  /** Initial conversation subject (defaults to `PENDING_SUBJECT`). */
   readonly subject?: string;
+  /** MCP server configurations to include for tool access. */
   readonly mcpServerUsages?: McpServerUsageInput[];
+  /** Skill references to enable for executions in this session. */
   readonly skillRefs?: ResourceRef[];
 }
 
@@ -32,8 +38,18 @@ interface SharedSessionFields {
  */
 export type CreateSessionInput = SharedSessionFields &
   (
-    | { readonly agentInstanceId: string; readonly agentRef?: never }
-    | { readonly agentRef: ResourceRef; readonly agentInstanceId?: never }
+    | {
+        /** Pre-provisioned AgentInstance ID to bind the session to. */
+        readonly agentInstanceId: string;
+        /** @internal Discriminant — excluded when `agentInstanceId` is provided. */
+        readonly agentRef?: never;
+      }
+    | {
+        /** Agent blueprint reference resolved to its default instance at creation time. */
+        readonly agentRef: ResourceRef;
+        /** @internal Discriminant — excluded when `agentRef` is provided. */
+        readonly agentInstanceId?: never;
+      }
   );
 
 /** Resolved output of {@link UseCreateSessionReturn.create}. */

package/src/session/useSession.ts

@@ -29,6 +29,30 @@ export interface UseSessionReturn {
  *
  * Returns the full proto {@link Session} resource so consumers have
  * access to metadata, spec, and status without additional calls.
+ *
+ * @example
+ * ```tsx
+ * function SessionDetail({ sessionId }: { sessionId: string }) {
+ *   const { session, isLoading, error, refetch } = useSession(sessionId);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *   if (!session) return <NotFound />;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{session.status?.subject ?? "Untitled session"}</h1>
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Skip fetching until session ID is available
+ * const { session } = useSession(sessionId ?? null);
+ * ```
  */
 export function useSession(id: string | null): UseSessionReturn {
   const stigmer = useStigmer();

package/src/session/useSessionArtifacts.ts

@@ -16,6 +16,7 @@ import { isTerminalPhase } from "../execution/execution-phases";
  * Apply CTA is enabled in the preview modal.
  */
 export interface SessionArtifactEntry {
+  /** The proto artifact record containing name, path, size, and download URL. */
   readonly artifact: ExecutionArtifact;
   /** ID of the execution that produced this artifact version. */
   readonly executionId: string;

package/src/session/useSessionConversation.ts

@@ -117,6 +117,7 @@ export interface UseSessionConversationReturn {
   readonly isSending: boolean;
   /** Error from the last sendFollowUp attempt, or null. */
   readonly sendError: Error | null;
+  /** Reset `sendError` to `null`. */
   readonly clearSendError: () => void;
 
   /** The user's message text, shown in the thread before the stream delivers it. */
@@ -139,13 +140,19 @@ export interface UseSessionConversationReturn {
   ) => Promise<void>;
   /** Set of tool call IDs currently being submitted for approval. */
   readonly submittingApprovalIds: ReadonlySet<string>;
+  /** Error from the last approval submission, or `null` when healthy. */
   readonly approvalError: Error | null;
+  /** Reset `approvalError` to `null`. */
   readonly clearApprovalError: () => void;
 
+  /** `true` while the session or execution list is loading. */
   readonly isLoading: boolean;
+  /** Error from session or execution list loading, or `null` when healthy. */
   readonly loadError: Error | null;
 
+  /** Error from the execution stream, or `null` when healthy. */
   readonly streamError: Error | null;
+  /** Reset the stream error and re-establish the execution stream subscription. */
   readonly reconnectStream: () => void;
 }
 

package/src/session/useSessionExecutions.ts

@@ -29,6 +29,29 @@ export interface UseSessionExecutionsReturn {
  * Returns up to 100 executions per call. Sessions rarely exceed a
  * handful of executions; full cursor-based pagination can be added
  * later without breaking the return type.
+ *
+ * @example
+ * ```tsx
+ * function ConversationThread({ sessionId }: { sessionId: string }) {
+ *   const { executions, isLoading } = useSessionExecutions(sessionId);
+ *   const stream = useExecutionStream(activeExecutionId);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *
+ *   return (
+ *     <MessageThread
+ *       executions={executions}
+ *       activeStreamExecution={stream.execution}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Skip fetching until a session is selected
+ * const { executions } = useSessionExecutions(sessionId ?? null);
+ * ```
  */
 export function useSessionExecutions(
   sessionId: string | null,

package/src/session/useSessionList.ts

@@ -37,6 +37,25 @@ const DEFAULT_PAGE_SIZE = 50;
  *
  * Returns up to `pageSize` sessions (default 50). Full cursor-based
  * pagination can be added later without breaking the return type.
+ *
+ * @example
+ * ```tsx
+ * function SessionSidebar() {
+ *   const { sessions, isLoading, refetch } = useSessionList({ pageSize: 25 });
+ *
+ *   if (isLoading) return <Skeleton />;
+ *
+ *   return (
+ *     <ul>
+ *       {sessions.map((s) => (
+ *         <li key={s.metadata?.id}>
+ *           {s.status?.subject ?? "Untitled"}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
  */
 export function useSessionList(
   options?: UseSessionListOptions,

package/src/session/useSessionWriteBacks.ts

@@ -12,6 +12,7 @@ import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agen
  * for traceability in the UI (e.g., tooltip or detail view).
  */
 export interface SessionWriteBackEntry {
+  /** The proto write-back record containing branch, PR URL, and commit details. */
   readonly writeBack: WorkspaceWriteBack;
   /** ID of the execution that produced this write-back. */
   readonly executionId: string;

package/src/session/useUpdateSession.ts

@@ -28,6 +28,28 @@ export interface UseUpdateSessionReturn {
  * {@link useSessionConversation} 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();
+ *
+ *   async function handleRename(newSubject: string) {
+ *     await update({
+ *       name: session.metadata!.name,
+ *       org: session.metadata!.org,
+ *       agentInstanceId: session.spec?.agentInstanceId,
+ *       subject: newSubject,
+ *     });
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleRename("New subject")} disabled={isUpdating}>
+ *       Rename
+ *     </button>
+ *   );
+ * }
+ * ```
  */
 export function useUpdateSession(): UseUpdateSessionReturn {
   const stigmer = useStigmer();

package/src/skill/SkillPicker.tsx

@@ -58,6 +58,21 @@ const LIST_ID = "stgm-skill-list";
  * Selected skills produce `ResourceRef[]` with `kind: skill`.
  *
  * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * function SkillSelector({ org }: { org: string }) {
+ *   const [skills, setSkills] = useState<ResourceRef[]>([]);
+ *
+ *   return (
+ *     <SkillPicker
+ *       org={org}
+ *       value={skills}
+ *       onChange={setSkills}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function SkillPicker({
   org,