@stigmer/react 0.0.70 → 0.0.72

package/src/composer/SessionComposer.tsx

@@ -72,6 +72,7 @@ export interface SessionComposerSubmitContext {
   readonly attachments?: AttachmentInput[];
 }
 
+/** Props for {@link SessionComposer}. */
 export interface SessionComposerProps {
   /**
    * Called when the user submits a message.
@@ -253,6 +254,7 @@ export interface SessionComposerProps {
   /** ARIA label for the composer region. @default "Send message" */
   readonly ariaLabel?: string;
 
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/composer/useComposer.ts

@@ -9,6 +9,7 @@ import {
   type RefObject,
 } from "react";
 
+/** Options for {@link useComposer}. */
 export interface UseComposerOptions {
   /** Called with the trimmed message when the user submits. */
   readonly onSubmit: (message: string) => void;
@@ -23,6 +24,7 @@ export interface UseComposerOptions {
   readonly autoFocusOnEnable?: boolean;
 }
 
+/** Return value of {@link useComposer}. */
 export interface UseComposerReturn {
   /** Current message text. */
   readonly message: string;

package/src/environment/CreateEnvironmentForm.tsx

@@ -10,6 +10,7 @@ import { useCreateEnvironment } from "./useCreateEnvironment";
 // Public API
 // ---------------------------------------------------------------------------
 
+/** Props for {@link CreateEnvironmentForm}. */
 export interface CreateEnvironmentFormProps {
   /** Organization slug. Used as the `org` field when creating the environment. */
   readonly org: string;
@@ -17,6 +18,7 @@ export interface CreateEnvironmentFormProps {
   readonly onCreated?: (env: Environment) => void;
   /** Fired when the user cancels. */
   readonly onCancel?: () => void;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/environment/EnvVarForm.tsx

@@ -29,6 +29,7 @@ export interface EnvVarFormSubmitOptions {
   readonly saveForFuture: boolean;
 }
 
+/** Props for {@link EnvVarForm}. */
 export interface EnvVarFormProps {
   /**
    * Variables to collect. Each entry renders one input field, in order.
@@ -47,6 +48,7 @@ export interface EnvVarFormProps {
   readonly onCancel?: () => void;
   /** When true, the submit button shows a spinner and inputs are disabled. */
   readonly isSubmitting?: boolean;
+  /** When `true`, all inputs and buttons are disabled. */
   readonly disabled?: boolean;
 
   /**
@@ -96,6 +98,7 @@ export interface EnvVarFormProps {
    * `pool.getAvailableValue` to look up pre-fill values.
    */
   readonly poolValues?: (key: string) => EnvVarInput | undefined;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
   /**
    * Overrides the `aria-label` on the `<form>` element. When omitted,

package/src/environment/EnvironmentListPanel.tsx

@@ -11,6 +11,7 @@ import { EnvironmentVariableEditor } from "./EnvironmentVariableEditor";
 // Public API
 // ---------------------------------------------------------------------------
 
+/** Props for {@link EnvironmentListPanel}. */
 export interface EnvironmentListPanelProps {
   /** Organization slug to list environments for. */
   readonly org: string;
@@ -28,6 +29,7 @@ export interface EnvironmentListPanelProps {
   readonly readOnly?: boolean;
   /** Re-expose refetch so parents can trigger a list refresh. */
   readonly onRefetchRef?: (refetch: () => void) => void;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/environment/EnvironmentVariableEditor.tsx

@@ -20,6 +20,7 @@ import { useRevealSecretValue } from "./useRevealSecretValue";
 // Public API
 // ---------------------------------------------------------------------------
 
+/** Props for {@link EnvironmentVariableEditor}. */
 export interface EnvironmentVariableEditorProps {
   /** The environment resource ID to display and manage variables for. */
   readonly environmentId: string;
@@ -29,6 +30,7 @@ export interface EnvironmentVariableEditorProps {
   readonly onVariableUpdated?: (key: string) => void;
   /** Fired after a variable is successfully removed. */
   readonly onVariableRemoved?: (key: string) => void;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/environment/useCreateEnvironment.ts

@@ -6,10 +6,15 @@ import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useCreateEnvironment}. */
 export interface UseCreateEnvironmentReturn {
+  /** Submit an {@link EnvironmentInput} to create a new Environment. Resolves with the server-created resource. */
   readonly create: (input: EnvironmentInput) => Promise<Environment>;
+  /** `true` while the create request is in flight. */
   readonly isCreating: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
   readonly clearError: () => void;
 }
 

package/src/environment/useEnvironment.ts

@@ -6,10 +6,15 @@ import type { ResourceRef } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useEnvironment}. */
 export interface UseEnvironmentReturn {
+  /** The fetched Environment, or `null` while loading or on error. */
   readonly environment: Environment | null;
+  /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
+  /** Discard cached data and re-fetch the environment from the server. */
   readonly refetch: () => void;
 }
 

package/src/environment/useEnvironmentList.ts

@@ -7,11 +7,17 @@ import { ListEnvironmentsRequestSchema } from "@stigmer/protos/ai/stigmer/agenti
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useEnvironmentList}. */
 export interface UseEnvironmentListReturn {
+  /** The fetched list of Environment entries. Empty while loading or on error. */
   readonly environments: readonly Environment[];
+  /** Total number of environments matching the query, including unpaged items. */
   readonly totalCount: number;
+  /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
+  /** Discard cached data and re-fetch the list from the server. */
   readonly refetch: () => void;
 }
 

package/src/environment/usePersonalEnvironment.ts

@@ -18,6 +18,7 @@ const PERSONAL_LABELS: Record<string, string> = {
   "stigmer.ai/personal": "true",
 };
 
+/** Return value of {@link usePersonalEnvironment}. */
 export interface UsePersonalEnvironmentReturn {
   /** The caller's personal environment, or `null` if not yet created or still loading. */
   readonly environment: Environment | null;

package/src/environment/useRemoveEnvironmentVariables.ts

@@ -19,12 +19,17 @@ export interface RemoveEnvironmentVariablesInput {
   readonly keys: string[];
 }
 
+/** Return value of {@link useRemoveEnvironmentVariables}. */
 export interface UseRemoveEnvironmentVariablesReturn {
+  /** Remove variables from an environment by key. Resolves with the updated resource. */
   readonly removeVariables: (
     input: RemoveEnvironmentVariablesInput,
   ) => Promise<Environment>;
+  /** `true` while the remove request is in flight. */
   readonly isRemovingVariables: boolean;
+  /** Error from the last failed removal, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
   readonly clearError: () => void;
 }
 

package/src/environment/useRevealSecretValue.ts

@@ -6,6 +6,7 @@ import { EnvironmentSecretValueInputSchema } from "@stigmer/protos/ai/stigmer/ag
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Options for {@link useRevealSecretValue}. */
 export interface UseRevealSecretValueOptions {
   /**
    * Milliseconds after which the revealed value is automatically cleared
@@ -17,6 +18,7 @@ export interface UseRevealSecretValueOptions {
   readonly autoClearMs?: number;
 }
 
+/** Return value of {@link useRevealSecretValue}. */
 export interface UseRevealSecretValueReturn {
   /**
    * Fetch and reveal a single secret value from an environment.

package/src/environment/useSessionEnvPool.ts

@@ -23,6 +23,7 @@ export interface SessionEnvPoolInput {
   readonly mcpRuntimeEnv?: Readonly<Record<string, EnvVarInput>>;
 }
 
+/** Return value of {@link useSessionEnvPool}. */
 export interface UseSessionEnvPoolReturn {
   /**
    * All env var keys currently available from any source.

package/src/environment/useUpdateEnvironment.ts

@@ -6,10 +6,15 @@ import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 
+/** Return value of {@link useUpdateEnvironment}. */
 export interface UseUpdateEnvironmentReturn {
+  /** Submit an {@link EnvironmentInput} to update an existing Environment. Resolves with the updated resource. */
   readonly update: (input: EnvironmentInput) => Promise<Environment>;
+  /** `true` while the update request is in flight. */
   readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
   readonly clearError: () => void;
 }
 

package/src/environment/useUpdateEnvironmentVariables.ts

@@ -23,12 +23,17 @@ export interface UpdateEnvironmentVariablesInput {
   readonly variables: Record<string, EnvVarInput>;
 }
 
+/** Return value of {@link useUpdateEnvironmentVariables}. */
 export interface UseUpdateEnvironmentVariablesReturn {
+  /** Add or update variables in an environment. Resolves with the updated resource. */
   readonly updateVariables: (
     input: UpdateEnvironmentVariablesInput,
   ) => Promise<Environment>;
+  /** `true` while the update request is in flight. */
   readonly isUpdatingVariables: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
   readonly error: Error | null;
+  /** Reset `error` to `null`. */
   readonly clearError: () => void;
 }
 

package/src/error/ErrorMessage.tsx

@@ -10,6 +10,7 @@ import {
 } from "@stigmer/sdk";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link ErrorMessage}. */
 export interface ErrorMessageProps {
   /** The error to display. Renders nothing when `null`. */
   readonly error: Error | null;
@@ -21,6 +22,7 @@ export interface ErrorMessageProps {
    * (server or unavailable category).
    */
   readonly retry?: () => void;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/error/SecretFlowErrorGuide.tsx

@@ -4,12 +4,14 @@ import { useMemo } from "react";
 import { StigmerError, getUserMessage } from "@stigmer/sdk";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link SecretFlowErrorGuide}. */
 export interface SecretFlowErrorGuideProps {
   /**
    * The error to inspect. Renders nothing when `null` or when the error
    * does not match a recognized secret-flow failure pattern.
    */
   readonly error: Error | null;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/ApprovalCard.tsx

@@ -11,7 +11,9 @@ import {
 import { CATEGORY_ICON } from "./ToolCallItem";
 import { ToolArgsView } from "./ToolArgsView";
 
+/** Props for {@link ApprovalCard}. */
 export interface ApprovalCardProps {
+  /** The pending approval request to render. */
   readonly pendingApproval: PendingApproval;
   /**
    * Called when the user clicks Approve, Skip, or Reject.
@@ -22,6 +24,7 @@ export interface ApprovalCardProps {
   readonly onSubmit: (action: ApprovalAction, comment?: string) => void;
   /** True while the RPC for this specific tool call is in flight. */
   readonly isSubmitting?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/ArtifactCard.tsx

@@ -16,6 +16,7 @@ import { useDetectSkillPackage } from "../library/useDetectSkillPackage";
  */
 const MAX_DETECTION_SIZE = 256 * 1024;
 
+/** Props for {@link ArtifactCard}. */
 export interface ArtifactCardProps {
   /** The execution artifact to render. */
   readonly artifact: ExecutionArtifact;

package/src/execution/ArtifactContentRenderer.tsx

@@ -12,6 +12,7 @@ import {
   type ArtifactRenderMode,
 } from "./artifact-utils";
 
+/** Props for {@link ArtifactContentRenderer}. */
 export interface ArtifactContentRendererProps {
   /** The text content to render. */
   readonly content: string;

package/src/execution/ArtifactPreviewModal.tsx

@@ -17,6 +17,7 @@ import {
 
 const COPIED_FEEDBACK_MS = 2000;
 
+/** Props for {@link ArtifactPreviewModal}. */
 export interface ArtifactPreviewModalProps {
   /** The execution artifact to preview. */
   readonly artifact: ExecutionArtifact;

package/src/execution/ArtifactsWidget.tsx

@@ -11,6 +11,7 @@ import { ArtifactCard } from "./ArtifactCard";
 import { ArtifactPreviewModal } from "./ArtifactPreviewModal";
 import type { ApplyResourceResult } from "../library/useApplyResource";
 
+/** Props for {@link ArtifactsWidget}. */
 export interface ArtifactsWidgetProps {
   /**
    * All executions for the current session — both completed and

package/src/execution/ExecutionPhaseBadge.tsx

@@ -3,8 +3,11 @@
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link ExecutionPhaseBadge}. */
 export interface ExecutionPhaseBadgeProps {
+  /** The execution phase to display. */
   readonly phase: ExecutionPhase;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/ExecutionProgress.tsx

@@ -5,9 +5,11 @@ import { cn } from "@stigmer/theme";
 import { ExecutionPhaseBadge } from "./ExecutionPhaseBadge";
 import { TodoList } from "./TodoList";
 
+/** Props for {@link ExecutionProgress}. */
 export interface ExecutionProgressProps {
   /** The execution to display progress for. Renders nothing when null. */
   readonly execution: AgentExecution | null;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/FilePathContext.tsx

@@ -11,6 +11,7 @@ import type { ResolvedPathAction } from "./file-path-resolver";
  * copy-to-clipboard for all paths.
  */
 export interface FilePathContextValue {
+  /** Workspace entries from the session spec, used for path resolution. */
   readonly workspaceEntries: readonly WorkspaceEntry[];
   /**
    * Optional override for the default click behavior. When provided,
@@ -28,5 +29,6 @@ const DEFAULT_VALUE: FilePathContextValue = {
   workspaceEntries: [],
 };
 
+/** Context that supplies workspace file-path metadata for display-time path resolution. */
 export const FilePathContext =
   createContext<FilePathContextValue>(DEFAULT_VALUE);

package/src/execution/FilePathLink.tsx

@@ -5,9 +5,11 @@ import { cn } from "@stigmer/theme";
 import { FilePathContext } from "./FilePathContext";
 import { resolvePathAction } from "./file-path-resolver";
 
+/** Props for {@link FilePathLink}. */
 export interface FilePathLinkProps {
   /** The workspace-relative file path from the tool call. */
   readonly path: string;
+  /** Additional CSS class names for the root element. */
   readonly className?: string;
 }
 

package/src/execution/FollowUpInput.tsx

@@ -10,6 +10,7 @@ import {
 import { cn } from "@stigmer/theme";
 import { ModelSelector } from "../models/ModelSelector";
 
+/** Props for {@link FollowUpInput}. */
 export interface FollowUpInputProps {
   /** Called when the user submits a message. */
   readonly onSubmit: (message: string, modelName?: string) => void;
@@ -25,6 +26,7 @@ export interface FollowUpInputProps {
   readonly onModelChange?: (modelId: string) => void;
   /** Placeholder text for the textarea. Default: "Reply...". */
   readonly placeholder?: string;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/McpToolDetail.tsx

@@ -13,8 +13,11 @@ import {
   humanizeArgKey,
 } from "./tool-rendering-primitives";
 
+/** Props for {@link McpToolDetail}. */
 export interface McpToolDetailProps {
+  /** The MCP tool call to render with structured formatting. */
   readonly toolCall: ToolCall;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 
@@ -63,6 +66,10 @@ export function McpToolDetail({ toolCall, className }: McpToolDetailProps) {
 // Metadata
 // ---------------------------------------------------------------------------
 
+/**
+ * Displays MCP server slug, tool name, and optional duration as a
+ * compact metadata row above tool arguments.
+ */
 export function McpMetadataRow({
   mcpServerSlug,
   toolName,
@@ -94,6 +101,12 @@ export function McpMetadataRow({
 // Arguments — structured key-value rendering
 // ---------------------------------------------------------------------------
 
+/**
+ * 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> }) {
   const entries = Object.entries(args);
   if (entries.length === 0) return null;

package/src/execution/MessageEntry.tsx

@@ -6,8 +6,11 @@ import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v
 import { cn } from "@stigmer/theme";
 import { MARKDOWN_COMPONENTS, REMARK_PLUGINS } from "../internal/markdown-components";
 
+/** Props for {@link MessageEntry}. */
 export interface MessageEntryProps {
+  /** The agent message to render. */
   readonly message: AgentMessage;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/MessageThread.tsx

@@ -25,6 +25,7 @@ import { FilePathContext, type FilePathContextValue } from "./FilePathContext";
 import type { ResolvedPathAction } from "./file-path-resolver";
 import { SandboxContext, type SandboxContextValue } from "./SandboxContext";
 
+/** Props for {@link MessageThread}. */
 export interface MessageThreadProps {
   /** Completed executions in chronological order. */
   readonly executions: readonly AgentExecution[];
@@ -41,6 +42,7 @@ export interface MessageThreadProps {
    * first snapshot.
    */
   readonly pendingUserMessage?: string | null;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
   /**
    * Custom formatter for tool call summary labels. Passed through to

package/src/execution/SessionVariablesInput.tsx

@@ -6,10 +6,13 @@ import type { UseSessionVariablesReturn } from "./useSessionVariables";
 import { useScrollShadows } from "../internal/useScrollShadows";
 import { ScrollFade } from "../internal/ScrollFade";
 
+/** Props for {@link SessionVariablesInput}. */
 export interface SessionVariablesInputProps {
   /** Hook instance returned by {@link useSessionVariables}. */
   readonly sessionVariables: UseSessionVariablesReturn;
+  /** Disable all inputs and buttons. */
   readonly disabled?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
   /**
    * Map of env-var keys to the names of resources that require them.

package/src/execution/SetupProgress.tsx

@@ -4,6 +4,7 @@ import { useEffect, useMemo, useState } from "react";
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link SetupProgress}. */
 export interface SetupProgressProps {
   /**
    * Workspace entries from the session spec. When git-sourced entries
@@ -21,6 +22,7 @@ export interface SetupProgressProps {
    * step sequence derived from `workspaceEntries`.
    */
   readonly serverPhase?: string;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/SubAgentSection.tsx

@@ -19,7 +19,9 @@ import {
   todoCompletionSummary,
 } from "./TodoList";
 
+/** Props for {@link SubAgentSection}. */
 export interface SubAgentSectionProps {
+  /** The sub-agent execution to render. */
   readonly subAgentExecution: SubAgentExecution;
   /**
    * Whether to render as a collapsible card with expand/collapse
@@ -29,6 +31,7 @@ export interface SubAgentSectionProps {
    * provides its own expand/collapse (e.g. {@link ToolCallItem}).
    */
   readonly collapsible?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/TodoList.tsx

@@ -5,12 +5,14 @@ import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution
 import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link TodoList}. */
 export interface TodoListProps {
   /**
    * Todo items keyed by ID. Accepts the proto map shape directly
    * (`execution.status.todos` or `subAgentExecution.todos`).
    */
   readonly todos: { readonly [key: string]: TodoItem };
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/ToolArgsView.tsx

@@ -20,6 +20,7 @@ import {
 // Public API
 // ---------------------------------------------------------------------------
 
+/** Props for {@link ToolArgsView}. */
 export interface ToolArgsViewProps {
   /**
    * Raw tool name as it appears on the ToolCall or PendingApproval.

package/src/execution/ToolCallDetail.tsx

@@ -13,8 +13,11 @@ import {
   formatResult,
 } from "./tool-rendering-primitives";
 
+/** Props for {@link ToolCallDetail}. */
 export interface ToolCallDetailProps {
+  /** The tool call to render in detail. */
   readonly toolCall: ToolCall;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/ToolCallGroup.tsx

@@ -11,7 +11,9 @@ import { cn } from "@stigmer/theme";
 import { ToolCallItem } from "./ToolCallItem";
 import { resolveToolCategory, extractPrimaryArg } from "./tool-categories";
 
+/** Props for {@link ToolCallGroup}. */
 export interface ToolCallGroupProps {
+  /** Tool calls in this group, ordered by invocation time. */
   readonly toolCalls: readonly ToolCall[];
   /**
    * Sub-agent executions from the parent `AgentExecutionStatus`.
@@ -30,6 +32,7 @@ export interface ToolCallGroupProps {
    * Initial expansion state. Defaults to `false`.
    */
   readonly defaultExpanded?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/ToolCallItem.tsx

@@ -18,7 +18,9 @@ import {
 } from "./tool-categories";
 import { useSandboxNormalize } from "./SandboxContext";
 
+/** Props for {@link ToolCallItem}. */
 export interface ToolCallItemProps {
+  /** The tool call to render as a summary row. */
   readonly toolCall: ToolCall;
   /**
    * When present, this tool call is a sub-agent delegation. The
@@ -30,6 +32,7 @@ export interface ToolCallItemProps {
    * Initial expansion state. Defaults to `false`.
    */
   readonly defaultExpanded?: boolean;
+  /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 

package/src/execution/UsageWidget.tsx

@@ -7,6 +7,7 @@ import {
   type ModelCostEntry,
 } from "../session/useSessionUsage";
 
+/** Props for {@link UsageWidget}. */
 export interface UsageWidgetProps {
   /**
    * All executions for the current session — both completed and

package/src/execution/WriteBackCard.tsx

@@ -4,6 +4,7 @@ import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agen
 import { WorkspaceWriteBackPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
 import { cn } from "@stigmer/theme";
 
+/** Props for {@link WriteBackCard}. */
 export interface WriteBackCardProps {
   /** The workspace write-back outcome to render. */
   readonly writeBack: WorkspaceWriteBack;

package/src/execution/WriteBacksWidget.tsx

@@ -5,6 +5,7 @@ import { cn } from "@stigmer/theme";
 import { useSessionWriteBacks } from "../session/useSessionWriteBacks";
 import { WriteBackCard } from "./WriteBackCard";
 
+/** Props for {@link WriteBacksWidget}. */
 export interface WriteBacksWidgetProps {
   /**
    * All executions for the current session — both completed and

package/src/execution/tool-categories.ts

@@ -24,10 +24,15 @@ export type ToolCategory =
   | "mcp"
   | "unknown";
 
+/** Resolved display metadata for a tool call, returned by {@link resolveToolCategory}. */
 export interface ToolCategoryInfo {
+  /** Semantic category of the tool. */
   readonly category: ToolCategory;
+  /** Human-readable label for the tool (e.g., `"Shell"`, `"Read"`). */
   readonly label: string;
+  /** JSON argument key that provides the primary display value (e.g., `"command"` for shell). */
   readonly primaryArgField: string;
+  /** Fallback argument keys tried when the primary key is absent. */
   readonly fallbackArgFields: readonly string[];
 }