@stigmer/react 0.0.71 → 0.0.73

package/session/useUpdateSession.js

@@ -12,6 +12,28 @@ import { useStigmer } from "../hooks";
  * {@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() {
     const stigmer = useStigmer();

package/session/useUpdateSession.js.map

@@ -1 +1 @@
-{"version":3,"file":"useUpdateSession.js","sourceRoot":"","sources":["../../src/session/useUpdateSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AActC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAG,WAAW,CACxB,KAAK,EAAE,KAAmB,EAAoB,EAAE;QAC9C,aAAa,CAAC,IAAI,CAAC,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,CAAC;YAClE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClB,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACnD,CAAC"}
+{"version":3,"file":"useUpdateSession.js","sourceRoot":"","sources":["../../src/session/useUpdateSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AActC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAG,WAAW,CACxB,KAAK,EAAE,KAAmB,EAAoB,EAAE;QAC9C,aAAa,CAAC,IAAI,CAAC,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,CAAC;YAClE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClB,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACnD,CAAC"}

package/skill/SkillPicker.d.ts

@@ -34,6 +34,21 @@ export interface SkillPickerProps {
  * 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 declare function SkillPicker({ org, scope, value, onChange, onDisplayNameResolved, disabled, className, }: SkillPickerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=SkillPicker.d.ts.map

package/skill/SkillPicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SkillPicker.d.ts","sourceRoot":"","sources":["../../src/skill/SkillPicker.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAQhD,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,KAAK,EACL,KAAK,EACL,QAAQ,EACR,qBAAqB,EACrB,QAAQ,EACR,SAAS,GACV,EAAE,gBAAgB,2CA8MlB"}
+{"version":3,"file":"SkillPicker.d.ts","sourceRoot":"","sources":["../../src/skill/SkillPicker.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAQhD,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,KAAK,EACL,KAAK,EACL,QAAQ,EACR,qBAAqB,EACrB,QAAQ,EACR,SAAS,GACV,EAAE,gBAAgB,2CA8MlB"}

package/skill/SkillPicker.js

@@ -20,6 +20,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, scope, value, onChange, onDisplayNameResolved, disabled, className, }) {
     const { results, isLoading, error, query, setQuery } = useSkillSearch(org, { scope });

package/skill/SkillPicker.js.map

@@ -1 +1 @@
-{"version":3,"file":"SkillPicker.js","sourceRoot":"","sources":["../../src/skill/SkillPicker.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"SkillPicker.js","sourceRoot":"","sources":["../../src/skill/SkillPicker.tsx"],"names":[],"mappings":"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"}

package/src/agent/AgentEnvForm.tsx

@@ -55,6 +55,7 @@ export interface AgentEnvFormProps {
   readonly onCancel?: () => void;
   /** When true, the submit button shows a spinner and inputs are disabled. */
   readonly isSubmitting?: boolean;
+  /** Prevents interaction with all form inputs when `true`. */
   readonly disabled?: boolean;
   /**
    * Initial state of the "Save for future runs" toggle.
@@ -75,6 +76,7 @@ export interface AgentEnvFormProps {
    * Passed through to {@link EnvVarForm}.
    */
   readonly poolValues?: EnvVarFormProps["poolValues"];
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/agent/AgentPicker.tsx

@@ -36,7 +36,9 @@ export interface AgentPickerProps {
    * @default "org"
    */
   readonly scope?: "org" | "all";
+  /** Prevents interaction with the picker when `true`. */
   readonly disabled?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/agent/agentSetupReducer.ts

@@ -18,9 +18,22 @@ import type { AgentEnvFormVariable } from "./AgentEnvForm";
  *   Create the session with `agentRef` directly.
  */
 export type AgentResolution =
-  | { readonly mode: "saved"; readonly instanceId: string }
-  | { readonly mode: "oneTime"; readonly runtimeEnv: Record<string, EnvVarInput> }
-  | { readonly mode: "direct" };
+  | {
+      /** Secrets were persisted to the user's personal environment. */
+      readonly mode: "saved";
+      /** ID of the personal agent instance to use for session creation. */
+      readonly instanceId: string;
+    }
+  | {
+      /** Secrets were collected but not persisted — pass to execution only. */
+      readonly mode: "oneTime";
+      /** Collected secrets to forward as execution-scoped runtime env vars. */
+      readonly runtimeEnv: Record<string, EnvVarInput>;
+    }
+  | {
+      /** The agent has no `env_spec` and needs no secrets. */
+      readonly mode: "direct";
+    };
 
 // ---------------------------------------------------------------------------
 // State machine — phases of the agent setup flow
@@ -36,26 +49,48 @@ export type AgentResolution =
  * narrowing in consumer code.
  */
 export type AgentSetupPhase =
-  | { readonly status: "idle" }
-  | { readonly status: "resolving"; readonly agentRef: ResourceRef }
   | {
+      /** No agent resolution has been initiated. */
+      readonly status: "idle";
+    }
+  | {
+      /** The agent blueprint is being fetched and its env spec is being evaluated. */
+      readonly status: "resolving";
+      /** Reference to the agent being resolved. */
+      readonly agentRef: ResourceRef;
+    }
+  | {
+      /** The agent requires environment variables that the user has not yet provided. */
       readonly status: "needsEnvVars";
+      /** Reference to the agent being set up. */
       readonly agentRef: ResourceRef;
+      /** Server-assigned ID of the agent blueprint. */
       readonly agentId: string;
+      /** Display name of the agent. */
       readonly agentName: string;
+      /** Environment variables the user must provide before proceeding. */
       readonly missingVariables: AgentEnvFormVariable[];
     }
   | {
+      /** Environment variables are being persisted or the instance is being provisioned. */
       readonly status: "submitting";
+      /** Reference to the agent being set up. */
       readonly agentRef: ResourceRef;
+      /** Server-assigned ID of the agent blueprint. */
       readonly agentId: string;
+      /** Display name of the agent. */
       readonly agentName: string;
+      /** Environment variables that were collected from the user. */
       readonly missingVariables: AgentEnvFormVariable[];
     }
   | {
+      /** The agent is fully resolved and ready for session creation. */
       readonly status: "ready";
+      /** Reference to the resolved agent. */
       readonly agentRef: ResourceRef;
+      /** Display name of the resolved agent. */
       readonly agentName: string;
+      /** How the agent was resolved — determines session creation strategy. */
       readonly resolution: AgentResolution;
     };
 
@@ -68,6 +103,7 @@ export type AgentSetupPhase =
  * error messages without losing the current phase context.
  */
 export type AgentSetupState = AgentSetupPhase & {
+  /** Error from the last async transition, or `null` when healthy. */
   readonly error: Error | null;
 };
 
@@ -76,63 +112,116 @@ export type AgentSetupState = AgentSetupPhase & {
 // ---------------------------------------------------------------------------
 
 /**
- * Result returned by {@link useAgentSetup.resolveAgent}.
+ * Result returned by `useAgentSetup().resolveAgent()`.
+ *
+ * - `"ready"` — the agent can be used immediately.
+ * - `"needsEnvVars"` — the agent requires environment variables
+ *   the user has not yet provided.
+ */
+/**
+ * Result returned by `useAgentSetup().submitEnvVars()` — always `"ready"`.
+ *
+ * Also used as the `"ready"` variant of {@link AgentSetupResult}.
+ */
+export interface AgentSetupReadyResult {
+  /** The agent is ready for session creation. */
+  readonly status: "ready";
+  /** Reference to the resolved agent. */
+  readonly agentRef: ResourceRef;
+  /** Display name of the resolved agent. */
+  readonly agentName: string;
+  /** How the agent was resolved — determines session creation strategy. */
+  readonly resolution: AgentResolution;
+}
+
+/**
+ * Result returned by `useAgentSetup().resolveAgent()`.
  *
  * - `"ready"` — the agent can be used immediately.
  * - `"needsEnvVars"` — the agent requires environment variables
  *   the user has not yet provided.
  */
 export type AgentSetupResult =
+  | AgentSetupReadyResult
   | {
-      readonly status: "ready";
-      readonly agentRef: ResourceRef;
-      readonly agentName: string;
-      readonly resolution: AgentResolution;
-    }
-  | {
+      /** The agent requires env vars the user has not yet provided. */
       readonly status: "needsEnvVars";
+      /** Reference to the agent being set up. */
       readonly agentRef: ResourceRef;
+      /** Display name of the agent. */
       readonly agentName: string;
+      /** Environment variables the user must provide before proceeding. */
       readonly missingVariables: AgentEnvFormVariable[];
     };
 
-/** Result returned by {@link useAgentSetup.submitEnvVars} — always `"ready"`. */
-export type AgentSetupReadyResult = AgentSetupResult & { readonly status: "ready" };
-
 // ---------------------------------------------------------------------------
 // Actions
 // ---------------------------------------------------------------------------
 
 /** Action union for the agent setup state machine managed by {@link agentSetupReducer}. */
 export type AgentSetupAction =
-  | { readonly type: "RESOLVE_START"; readonly agentRef: ResourceRef }
   | {
+      /** Begin resolving an agent's requirements. */
+      readonly type: "RESOLVE_START";
+      /** Reference to the agent to resolve. */
+      readonly agentRef: ResourceRef;
+    }
+  | {
+      /** Agent resolved but requires env vars from the user. */
       readonly type: "RESOLVE_NEEDS_ENV";
+      /** Reference to the agent. */
       readonly agentRef: ResourceRef;
+      /** Server-assigned agent ID. */
       readonly agentId: string;
+      /** Display name of the agent. */
       readonly agentName: string;
+      /** Variables the user must provide. */
       readonly missingVariables: AgentEnvFormVariable[];
     }
   | {
+      /** Agent resolved and is ready for session creation. */
       readonly type: "RESOLVE_READY";
+      /** Reference to the resolved agent. */
       readonly agentRef: ResourceRef;
+      /** Display name of the resolved agent. */
       readonly agentName: string;
+      /** Resolution strategy for session creation. */
       readonly resolution: AgentResolution;
     }
   | {
+      /** Re-evaluate missing variables after pool values arrive. */
       readonly type: "POOL_RESOLVE";
+      /** Updated missing variables (may be empty if pool covered all). */
       readonly missingVariables: AgentEnvFormVariable[];
     }
-  | { readonly type: "SUBMIT_START" }
   | {
+      /** Begin persisting env vars or creating an agent instance. */
+      readonly type: "SUBMIT_START";
+    }
+  | {
+      /** Env var submission succeeded — agent is ready. */
       readonly type: "SUBMIT_READY";
+      /** Reference to the resolved agent. */
       readonly agentRef: ResourceRef;
+      /** Display name of the resolved agent. */
       readonly agentName: string;
+      /** Resolution strategy for session creation. */
       readonly resolution: AgentResolution;
     }
-  | { readonly type: "ERROR"; readonly error: Error }
-  | { readonly type: "CLEAR_ERROR" }
-  | { readonly type: "RESET" };
+  | {
+      /** An async operation failed. */
+      readonly type: "ERROR";
+      /** The error that occurred. */
+      readonly error: Error;
+    }
+  | {
+      /** Clear the error without changing phase. */
+      readonly type: "CLEAR_ERROR";
+    }
+  | {
+      /** Reset to idle state. */
+      readonly type: "RESET";
+    };
 
 // ---------------------------------------------------------------------------
 // Reducer

package/src/agent/useAgentCount.ts

@@ -26,7 +26,9 @@ export interface UseAgentCountReturn {
    * until the first successful fetch completes.
    */
   readonly count: number | undefined;
+  /** `true` while the count fetch is in flight. */
   readonly isLoading: boolean;
+  /** Error message from the last failed fetch, or `null` when healthy. */
   readonly error: string | null;
   /** Re-fetch the count with the same parameters. */
   readonly refetch: () => void;

package/src/attachment/AttachmentChipList.tsx

@@ -27,6 +27,21 @@ export interface AttachmentChipListProps {
  * who compose their own attachment UI.
  *
  * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * function CustomComposer() {
+ *   const attachments = useAttachments({ sessionId });
+ *
+ *   return (
+ *     <AttachmentChipList
+ *       entries={attachments.entries}
+ *       onRemove={attachments.remove}
+ *       onRetry={attachments.retry}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function AttachmentChipList({
   entries,

package/src/attachment/useAttachments.ts

@@ -31,6 +31,20 @@ export type AttachmentPhase = "uploading" | "ready" | "error";
  * The `id` is a stable string generated at add-time, used as a React
  * key and for removal. The same `File` added twice produces two
  * independent entries with distinct IDs.
+ *
+ * @example
+ * ```tsx
+ * const attachments = useAttachments();
+ *
+ * attachments.entries.map((entry) => (
+ *   <span key={entry.id}>
+ *     {entry.file.name}
+ *     {entry.phase === "uploading" && <Spinner />}
+ *     {entry.phase === "error" && <span>{entry.error}</span>}
+ *     {entry.phase === "ready" && <CheckIcon />}
+ *   </span>
+ * ));
+ * ```
  */
 export interface AttachmentEntry {
   /** Unique client-side identifier for this attachment. */

package/src/composer/useComposer.ts

@@ -40,10 +40,15 @@ export interface UseComposerReturn {
    * then specifying overrides.
    */
   readonly textareaProps: {
+    /** Ref to the underlying `<textarea>` element. */
     readonly ref: RefObject<HTMLTextAreaElement | null>;
+    /** Current message text bound to the textarea. */
     readonly value: string;
+    /** Change handler that updates message state and triggers auto-resize. */
     readonly onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    /** Key handler that submits on Enter and allows Shift+Enter for newlines. */
     readonly onKeyDown: (e: KeyboardEvent<HTMLTextAreaElement>) => void;
+    /** Whether the textarea is disabled (prevents typing and submission). */
     readonly disabled: boolean;
   };
   /** Whether the current message is non-empty and the input is not disabled. */

package/src/execution/ExecutionPhaseBadge.tsx

@@ -85,7 +85,7 @@ const PHASE_CONFIG: ReadonlyMap<ExecutionPhase, PhaseConfig> = new Map([
 ]);
 
 /**
- * Displays the lifecycle phase of an {@link AgentExecution} as an
+ * Displays the lifecycle phase of an `AgentExecution` as an
  * inline badge with a status icon and label.
  *
  * Renders nothing for `EXECUTION_PHASE_UNSPECIFIED`.

package/src/execution/McpToolDetail.tsx

@@ -66,6 +66,16 @@ export function McpToolDetail({ toolCall, className }: McpToolDetailProps) {
 // Metadata
 // ---------------------------------------------------------------------------
 
+/** Props for {@link McpMetadataRow}. */
+export interface McpMetadataRowProps {
+  /** Slug of the MCP server that owns the tool. */
+  readonly mcpServerSlug: string;
+  /** Name of the tool that was invoked. */
+  readonly toolName: string;
+  /** Human-readable execution duration, or `null` if still running. */
+  readonly duration: string | null;
+}
+
 /**
  * Displays MCP server slug, tool name, and optional duration as a
  * compact metadata row above tool arguments.
@@ -74,11 +84,7 @@ export function McpMetadataRow({
   mcpServerSlug,
   toolName,
   duration,
-}: {
-  mcpServerSlug: string;
-  toolName: string;
-  duration: string | null;
-}) {
+}: McpMetadataRowProps) {
   const hasMetadata = mcpServerSlug || duration;
   if (!hasMetadata) return null;
 
@@ -101,13 +107,19 @@ export function McpMetadataRow({
 // Arguments — structured key-value rendering
 // ---------------------------------------------------------------------------
 
+/** Props for {@link McpArgsView}. */
+export interface McpArgsViewProps {
+  /** Tool argument map to render as a key-value list. */
+  readonly args: Record<string, unknown>;
+}
+
 /**
  * Renders MCP tool arguments as a structured key-value list.
  *
  * Scalars display inline; objects and arrays collapse into
  * formatted JSON blocks via {@link CollapsibleJsonBlock}.
  */
-export function McpArgsView({ args }: { args: Record<string, unknown> }) {
+export function McpArgsView({ args }: McpArgsViewProps) {
   const entries = Object.entries(args);
   if (entries.length === 0) return null;
 

package/src/execution/TodoList.tsx

@@ -38,6 +38,14 @@ function todoSortKey(item: TodoItem): number {
  * task description.
  *
  * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * const execution = stream.execution;
+ * const todos = execution?.status?.todos ?? {};
+ *
+ * <TodoList todos={todos} />
+ * ```
  */
 export function TodoList({ todos, className }: TodoListProps) {
   const sortedTodos = useMemo(() => {

package/src/execution/ToolArgsView.tsx

@@ -34,6 +34,7 @@ export interface ToolArgsViewProps {
   readonly args: Record<string, unknown> | null;
   /** MCP server slug for MCP tool classification and metadata. */
   readonly mcpServerSlug?: string;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/UsageWidget.tsx

@@ -25,7 +25,7 @@ export interface UsageWidgetProps {
 
 /**
  * Right-sidebar widget that displays session-level cost and token
- * usage aggregated from per-message {@link LlmCallMetrics}.
+ * usage aggregated from per-message `LlmCallMetrics`.
  *
  * Usage data is computed purely from messages the frontend already
  * has — no server RPC is required for the real-time widget.

package/src/execution/file-path-resolver.ts

@@ -8,8 +8,18 @@ const PLATFORM_DIR_NAME = ".stigmer";
  * platform mount (`.stigmer/`) namespace.
  */
 export type PathClassification =
-  | { readonly kind: "workspace"; readonly remainder: string }
-  | { readonly kind: "platform"; readonly subpath: string };
+  | {
+      /** The path targets a workspace source entry. */
+      readonly kind: "workspace";
+      /** Path relative to the workspace root, with `.stigmer/` prefix stripped. */
+      readonly remainder: string;
+    }
+  | {
+      /** The path targets the virtual platform mount (`.stigmer/`). */
+      readonly kind: "platform";
+      /** Path within the platform namespace, after the `.stigmer/` prefix. */
+      readonly subpath: string;
+    };
 
 /**
  * Classifies whether a path targets the virtual platform mount
@@ -80,8 +90,22 @@ export function resolveGitBrowseUrl(
  * to decide rendering (anchor vs. copy button).
  */
 export type ResolvedPathAction =
-  | { readonly action: "link"; readonly url: string; readonly tooltip: string }
-  | { readonly action: "copy"; readonly value: string; readonly tooltip: string };
+  | {
+      /** Open the path as a navigable URL (e.g. GitHub blob link). */
+      readonly action: "link";
+      /** Resolved external URL to open. */
+      readonly url: string;
+      /** Human-readable label for the link action. */
+      readonly tooltip: string;
+    }
+  | {
+      /** Copy the path to the clipboard (no navigable URL available). */
+      readonly action: "copy";
+      /** Resolved path string to copy. */
+      readonly value: string;
+      /** Human-readable label for the copy action. */
+      readonly tooltip: string;
+    };
 
 /**
  * Resolves a tool-call file path to a user action.

package/src/execution/index.ts

@@ -48,7 +48,11 @@ export { ToolCallDetail, formatDuration } from "./ToolCallDetail";
 export type { ToolCallDetailProps } from "./ToolCallDetail";
 
 export { McpToolDetail, McpArgsView, McpMetadataRow, parseMcpResult } from "./McpToolDetail";
-export type { McpToolDetailProps } from "./McpToolDetail";
+export type {
+  McpToolDetailProps,
+  McpArgsViewProps,
+  McpMetadataRowProps,
+} from "./McpToolDetail";
 
 export { ToolArgsView } from "./ToolArgsView";
 export type { ToolArgsViewProps } from "./ToolArgsView";

package/src/execution/useArtifactContent.ts

@@ -86,6 +86,39 @@ export interface UseArtifactContentReturn {
  *   stable but `contentHash` changes, triggering a re-fetch so the UI never
  *   shows stale content. Pass `undefined` or omit for backwards compatibility.
  *
+ * @example
+ * ```tsx
+ * function ArtifactViewer({ executionId, artifact }: {
+ *   executionId: string;
+ *   artifact: ExecutionArtifact;
+ * }) {
+ *   const shouldFetch = isTextArtifact(artifact)
+ *     && Number(artifact.sizeBytes) < 512_000;
+ *
+ *   const { content, contentType, isTruncated, isLoading } = useArtifactContent(
+ *     shouldFetch ? executionId : null,
+ *     shouldFetch ? artifact.storageKey : null,
+ *   );
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (!content) return null;
+ *
+ *   return (
+ *     <ArtifactContentRenderer
+ *       content={content}
+ *       contentType={contentType}
+ *       isTruncated={isTruncated}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Extract a single file from a directory artifact
+ * const { content } = useArtifactContent(executionId, storageKey, "SKILL.md");
+ * ```
+ *
  * @see useExecutionArtifacts — extracts artifact metadata from an execution
  * @see isTextArtifact — heuristic for whether content is fetchable as text
  */

package/src/execution/useSubmitApproval.ts

@@ -26,7 +26,9 @@ export interface UseSubmitApprovalReturn {
    * approve one tool while another decision is still in flight.
    */
   readonly submittingToolCallIds: ReadonlySet<string>;
+  /** Error from the last failed approval submission, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
   readonly clearError: () => void;
 }