@stigmer/react 0.0.36 → 0.0.39

package/src/index.ts

@@ -4,3 +4,370 @@ export { StigmerContext } from "./context";
 
 // Hooks
 export { useStigmer } from "./hooks";
+
+// Models — data hook, styled component, and registry data
+export {
+  MODEL_REGISTRY,
+  DEFAULT_MODEL_ID,
+  useModelRegistry,
+  ModelSelector,
+} from "./models";
+export type {
+  ModelInfo,
+  Provider,
+  CostTier,
+  UseModelRegistryReturn,
+  ModelSelectorProps,
+} from "./models";
+
+// Workspace — behavior hooks, data hook, and styled components
+export {
+  useWorkspaceEntries,
+  WorkspaceEditor,
+  useFolderListing,
+  FolderBrowser,
+  WorkspaceSummary,
+} from "./workspace";
+export type {
+  WorkspaceEntry,
+  UseWorkspaceEntriesReturn,
+  WorkspaceEditorProps,
+  FolderEntry,
+  FolderListing,
+  UseFolderListingReturn,
+  FolderBrowserProps,
+  WorkspaceSummaryProps,
+} from "./workspace";
+
+// Session — data hooks, behavior hooks, utilities (Session aggregate + conversation lifecycle)
+export {
+  useCreateSession,
+  useUpdateSession,
+  useSession,
+  useSessionList,
+  useSessionExecutions,
+  useSessionConversation,
+  useAgentRefFromSession,
+  groupSessionsByTime,
+} from "./session";
+export type {
+  CreateSessionInput,
+  CreateSessionResult,
+  UseCreateSessionReturn,
+  UseUpdateSessionReturn,
+  UseSessionReturn,
+  UseSessionListOptions,
+  UseSessionListReturn,
+  UseSessionExecutionsReturn,
+  SendFollowUpOptions,
+  UseSessionConversationReturn,
+  UseAgentRefFromSessionReturn,
+  SessionGroup,
+} from "./session";
+
+// Execution — behavior hooks, styled components, and utilities (AgentExecution aggregate)
+export {
+  isTerminalPhase,
+  useCreateAgentExecution,
+  useExecutionStream,
+  useExecutionUsage,
+  aggregateUsage,
+  useSubmitApproval,
+  ExecutionPhaseBadge,
+  ExecutionProgress,
+  ExecutionCostSummary,
+  ToolCallGroup,
+  ToolCallDetail,
+  formatDuration,
+  ToolCallItem,
+  SubAgentSection,
+  MessageEntry,
+  MessageThread,
+  FollowUpInput,
+  ApprovalCard,
+  ArtifactCard,
+  ArtifactPreviewModal,
+  ArtifactsWidget,
+  FilePathLink,
+  FilePathContext,
+  classifyPath,
+  resolveGitBrowseUrl,
+  resolvePathAction,
+  useSessionVariables,
+  SessionVariablesInput,
+  useExecutionArtifacts,
+  useArtifactContent,
+  isTextArtifact,
+  isArtifactExpired,
+  formatArtifactSize,
+  getArtifactExtension,
+} from "./execution";
+export type {
+  CreateAgentExecutionInput,
+  CreateAgentExecutionResult,
+  UseCreateAgentExecutionReturn,
+  UseExecutionStreamReturn,
+  UseExecutionUsageReturn,
+  UseSubmitApprovalReturn,
+  ExecutionPhaseBadgeProps,
+  ExecutionProgressProps,
+  ExecutionCostSummaryProps,
+  ToolCallGroupProps,
+  ToolCallDetailProps,
+  ToolCallItemProps,
+  SubAgentSectionProps,
+  MessageEntryProps,
+  MessageThreadProps,
+  FollowUpInputProps,
+  ApprovalCardProps,
+  ArtifactCardProps,
+  ArtifactPreviewModalProps,
+  ArtifactsWidgetProps,
+  FilePathLinkProps,
+  FilePathContextValue,
+  PathClassification,
+  ResolvedPathAction,
+  SessionVariableEntry,
+  UseSessionVariablesReturn,
+  SessionVariablesInputProps,
+  UseExecutionArtifactsReturn,
+  UseArtifactContentReturn,
+} from "./execution";
+
+// Execution — proto type re-exports for artifact consumers
+export type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+export { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+// Attachment — file upload behavior hook and styled chip list
+export {
+  useAttachments,
+  AttachmentChipList,
+  MAX_ATTACHMENT_BYTES,
+  detectContentType,
+  formatFileSize,
+  validateAttachmentSize,
+} from "./attachment";
+export type {
+  AttachmentPhase,
+  AttachmentEntry,
+  UseAttachmentsOptions,
+  UseAttachmentsReturn,
+  AttachmentChipListProps,
+} from "./attachment";
+
+// Composer — unified message input with model, workspace, and file attachments
+export {
+  useComposer,
+  SessionComposer,
+} from "./composer";
+export type {
+  UseComposerOptions,
+  UseComposerReturn,
+  SessionComposerProps,
+  SessionComposerSubmitContext,
+} from "./composer";
+
+// MCP Server — data hook, count hook, list hook, search hook, picker, config panel, tool selector, detail view, and setup orchestration
+export {
+  useMcpServer,
+  useMcpServerCount,
+  useMcpServerList,
+  useMcpServerSearch,
+  useMcpServerSetup,
+  McpServerPicker,
+  McpServerConfigPanel,
+  McpServerDetailView,
+  McpToolSelector,
+  toServerKey,
+} from "./mcp-server";
+export type {
+  UseMcpServerReturn,
+  UseMcpServerCountOptions,
+  UseMcpServerCountReturn,
+  UseMcpServerListOptions,
+  UseMcpServerListReturn,
+  UseMcpServerSearchOptions,
+  UseMcpServerSearchReturn,
+  UseMcpServerSetupReturn,
+  SubmitMcpEnvVarsOptions,
+  McpServerSetupEntry,
+  McpServerSetupPhase,
+  McpServerSetupState,
+  McpServerPickerProps,
+  McpServerSetupIntegration,
+  McpServerConfigPanelProps,
+  McpServerCredentialsProps,
+  McpServerDetailViewProps,
+  McpToolSelectorProps,
+} from "./mcp-server";
+
+// Skill — data hook, count hook, list hook, search hook, picker, and detail view component
+export {
+  useSkill,
+  useSkillCount,
+  useSkillList,
+  useSkillSearch,
+  SkillPicker,
+  SkillDetailView,
+} from "./skill";
+export type {
+  UseSkillReturn,
+  UseSkillCountOptions,
+  UseSkillCountReturn,
+  UseSkillListOptions,
+  UseSkillListReturn,
+  UseSkillSearchOptions,
+  UseSkillSearchReturn,
+  SkillPickerProps,
+  SkillDetailViewProps,
+} from "./skill";
+
+// GitHub — OAuth connection, repo picker, and hooks
+export {
+  useGitHubConnection,
+  useGitHubRepos,
+  GitHubRepoPicker,
+  GITHUB_CALLBACK_MESSAGE_TYPE,
+} from "./github";
+export type {
+  GitHubUser,
+  GitHubConnectOptions,
+  UseGitHubConnectionReturn,
+  GitHubRepo,
+  GitHubBranch,
+  UseGitHubReposReturn,
+  GitHubRepoPickerProps,
+} from "./github";
+
+// Agent — data hook, count hook, list hook, search hook, picker, detail view, env form, setup orchestration, env_spec diffing, and default agent
+export {
+  useAgent,
+  useAgentCount,
+  useAgentList,
+  useAgentSearch,
+  AgentPicker,
+  AgentDetailView,
+  AgentEnvForm,
+  diffEnvSpec,
+  useAgentSetup,
+  useDefaultAgent,
+} from "./agent";
+export type {
+  UseAgentReturn,
+  UseAgentCountOptions,
+  UseAgentCountReturn,
+  UseAgentListOptions,
+  UseAgentListReturn,
+  UseAgentSearchOptions,
+  UseAgentSearchReturn,
+  AgentPickerProps,
+  AgentDetailViewProps,
+  AgentEnvFormProps,
+  AgentEnvFormSubmitOptions,
+  AgentEnvFormVariable,
+  AgentSetupResult,
+  AgentSetupReadyResult,
+  AgentSetupState,
+  AgentSetupPhase,
+  AgentResolution,
+  SubmitEnvVarsOptions,
+  UseAgentSetupReturn,
+  UseDefaultAgentReturn,
+} from "./agent";
+
+// Environment — data hooks, list hook, personal convenience hook, secret reveal, variable management, env var form, and styled components
+export {
+  useEnvironment,
+  useEnvironmentList,
+  usePersonalEnvironment,
+  useCreateEnvironment,
+  useUpdateEnvironment,
+  useUpdateEnvironmentVariables,
+  useRemoveEnvironmentVariables,
+  useRevealSecretValue,
+  EnvironmentVariableEditor,
+  EnvironmentListPanel,
+  CreateEnvironmentForm,
+  EnvVarForm,
+  useSessionEnvPool,
+} from "./environment";
+export type {
+  UseEnvironmentReturn,
+  UseEnvironmentListReturn,
+  UsePersonalEnvironmentReturn,
+  UseCreateEnvironmentReturn,
+  UseUpdateEnvironmentReturn,
+  UpdateEnvironmentVariablesInput,
+  UseUpdateEnvironmentVariablesReturn,
+  RemoveEnvironmentVariablesInput,
+  UseRemoveEnvironmentVariablesReturn,
+  UseRevealSecretValueOptions,
+  UseRevealSecretValueReturn,
+  EnvironmentVariableEditorProps,
+  EnvironmentListPanelProps,
+  CreateEnvironmentFormProps,
+  EnvVarFormProps,
+  EnvVarFormVariable,
+  EnvVarFormSubmitOptions,
+  SessionEnvPoolInput,
+  UseSessionEnvPoolReturn,
+} from "./environment";
+
+// Organization — behavior hook and styled form for organization creation
+export {
+  useCreateOrganization,
+  CreateOrganizationForm,
+} from "./organization";
+export type {
+  UseCreateOrganizationReturn,
+  CreateOrganizationFormProps,
+} from "./organization";
+
+// Error — structured error display with classification, retry, and contextual guidance
+export { ErrorMessage, SecretFlowErrorGuide, isSecretFlowError } from "./error";
+export type { ErrorMessageProps, SecretFlowErrorGuideProps } from "./error";
+
+// Library — cross-resource UI components, resource detection, apply flow, and browsing
+export {
+  ScopeToggle,
+  ResourceListView,
+  ResourceCountCard,
+  detectStigmerResource,
+  useDetectStigmerResource,
+  isSkillPackage,
+  detectSkillPackage,
+  useDetectSkillPackage,
+  parseResourceYaml,
+  serializeAgentYaml,
+  serializeMcpServerYaml,
+  useApplyResource,
+} from "./library";
+export type {
+  ScopeToggleProps,
+  ResourceListViewProps,
+  ResourceCountCardProps,
+  ResourceListScope,
+  StigmerResourceKind,
+  StigmerResourceDetection,
+  SkillPackageDetection,
+  UseDetectSkillPackageReturn,
+  ParsedResource,
+  UseApplyResourceReturn,
+  ApplyResourceResult,
+  PushSkillParams,
+} from "./library";
+
+// Agent Instance — data hooks, list hook, personal convenience hook, and behavior hook
+export {
+  useAgentInstance,
+  useAgentInstanceList,
+  usePersonalAgentInstance,
+  useCreateAgentInstance,
+} from "./agent-instance";
+export type {
+  UseAgentInstanceReturn,
+  UseAgentInstanceListReturn,
+  GetOrCreatePersonalInstanceInput,
+  UsePersonalAgentInstanceReturn,
+  UseCreateAgentInstanceReturn,
+} from "./agent-instance";

package/src/internal/ScrollFade.tsx

@@ -0,0 +1,29 @@
+/**
+ * Gradient overlay that signals hidden content above or below a
+ * scrollable container. Renders a `pointer-events-none` absolutely
+ * positioned `div` — the parent must be `position: relative`.
+ *
+ * Uses `--color-popover` with a fallback so the gradient blends
+ * into the most common container background. A future iteration may
+ * introduce a dedicated `--stgm-scroll-fade` token.
+ *
+ * @internal
+ */
+export function ScrollFade({ position }: { readonly position: "top" | "bottom" }) {
+  const isTop = position === "top";
+
+  return (
+    <div
+      className={[
+        "pointer-events-none absolute inset-x-0 z-10 h-3",
+        isTop ? "top-0" : "bottom-0",
+      ].join(" ")}
+      style={{
+        background: isTop
+          ? "linear-gradient(to bottom, var(--color-popover, hsl(0 0% 9%)), transparent)"
+          : "linear-gradient(to top, var(--color-popover, hsl(0 0% 9%)), transparent)",
+      }}
+      aria-hidden="true"
+    />
+  );
+}

package/src/internal/markdown-components.tsx

@@ -0,0 +1,197 @@
+import type { ComponentProps, JSX } from "react";
+import type { Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { cn } from "@stigmer/theme";
+
+type MdProps<T extends keyof JSX.IntrinsicElements> = ComponentProps<T>;
+
+/**
+ * Remark plugins applied to all SDK markdown surfaces.
+ * Includes GFM (tables, strikethrough, autolinks, task lists).
+ */
+export const REMARK_PLUGINS = [remarkGfm];
+
+/**
+ * Styled react-markdown component overrides for SDK markdown surfaces.
+ *
+ * Every element uses `--stgm-*` design tokens via Tailwind semantic classes,
+ * ensuring correct rendering in both the Stigmer Console and third-party
+ * host applications with custom themes.
+ *
+ * Used by `MessageEntry` (chat messages) and `SkillDetailView` (SKILL.md).
+ */
+export const MARKDOWN_COMPONENTS: Components = {
+  p({ children, ...props }: MdProps<"p">) {
+    return (
+      <p className="text-sm text-foreground mb-3 last:mb-0 leading-relaxed" {...props}>
+        {children}
+      </p>
+    );
+  },
+
+  a({ children, href, ...props }: MdProps<"a">) {
+    return (
+      <a
+        href={href}
+        className="text-primary underline underline-offset-2 hover:text-primary/80"
+        target="_blank"
+        rel="noopener noreferrer"
+        {...props}
+      >
+        {children}
+      </a>
+    );
+  },
+
+  h1({ children, ...props }: MdProps<"h1">) {
+    return (
+      <h1 className="text-lg font-semibold text-foreground mt-5 mb-2 first:mt-0" {...props}>
+        {children}
+      </h1>
+    );
+  },
+
+  h2({ children, ...props }: MdProps<"h2">) {
+    return (
+      <h2 className="text-base font-semibold text-foreground mt-5 mb-2 first:mt-0" {...props}>
+        {children}
+      </h2>
+    );
+  },
+
+  h3({ children, ...props }: MdProps<"h3">) {
+    return (
+      <h3 className="text-sm font-semibold text-foreground mt-4 mb-1.5 first:mt-0" {...props}>
+        {children}
+      </h3>
+    );
+  },
+
+  h4({ children, ...props }: MdProps<"h4">) {
+    return (
+      <h4 className="text-sm font-medium text-foreground mt-3 mb-1 first:mt-0" {...props}>
+        {children}
+      </h4>
+    );
+  },
+
+  ul({ children, ...props }: MdProps<"ul">) {
+    return (
+      <ul className="list-disc pl-5 mb-3 last:mb-0 space-y-1 text-sm text-foreground" {...props}>
+        {children}
+      </ul>
+    );
+  },
+
+  ol({ children, ...props }: MdProps<"ol">) {
+    return (
+      <ol className="list-decimal pl-5 mb-3 last:mb-0 space-y-1 text-sm text-foreground" {...props}>
+        {children}
+      </ol>
+    );
+  },
+
+  li({ children, ...props }: MdProps<"li">) {
+    return (
+      <li className="leading-relaxed" {...props}>
+        {children}
+      </li>
+    );
+  },
+
+  pre({ children, ...props }: MdProps<"pre">) {
+    return (
+      <pre
+        className="mb-3 last:mb-0 overflow-x-auto rounded-md bg-muted p-3"
+        {...props}
+      >
+        {children}
+      </pre>
+    );
+  },
+
+  code({ children, className: codeClassName, ...props }: MdProps<"code">) {
+    const isBlock =
+      typeof codeClassName === "string" && codeClassName.startsWith("language-");
+
+    if (isBlock) {
+      return (
+        <code
+          className={cn("font-mono text-xs text-foreground", codeClassName)}
+          {...props}
+        >
+          {children}
+        </code>
+      );
+    }
+
+    return (
+      <code
+        className="font-mono text-xs bg-muted px-1 py-0.5 rounded text-foreground"
+        {...props}
+      >
+        {children}
+      </code>
+    );
+  },
+
+  blockquote({ children, ...props }: MdProps<"blockquote">) {
+    return (
+      <blockquote
+        className="border-l-2 border-border pl-4 mb-3 last:mb-0 text-muted-foreground italic"
+        {...props}
+      >
+        {children}
+      </blockquote>
+    );
+  },
+
+  table({ children, ...props }: MdProps<"table">) {
+    return (
+      <div className="mb-3 last:mb-0 overflow-x-auto">
+        <table className="w-full border-collapse text-sm" {...props}>
+          {children}
+        </table>
+      </div>
+    );
+  },
+
+  th({ children, ...props }: MdProps<"th">) {
+    return (
+      <th
+        className="border border-border px-3 py-1.5 text-left font-medium text-foreground bg-muted/50"
+        {...props}
+      >
+        {children}
+      </th>
+    );
+  },
+
+  td({ children, ...props }: MdProps<"td">) {
+    return (
+      <td className="border border-border px-3 py-1.5 text-foreground" {...props}>
+        {children}
+      </td>
+    );
+  },
+
+  hr(props: MdProps<"hr">) {
+    return <hr className="my-4 border-border" {...props} />;
+  },
+
+  strong({ children, ...props }: MdProps<"strong">) {
+    return (
+      <strong className="font-semibold text-foreground" {...props}>
+        {children}
+      </strong>
+    );
+  },
+
+  em({ children, ...props }: MdProps<"em">) {
+    return (
+      <em className="italic" {...props}>
+        {children}
+      </em>
+    );
+  },
+};

package/src/internal/slug.ts

@@ -0,0 +1,41 @@
+/**
+ * Derives a URL-friendly slug from a human-readable name.
+ *
+ * This mirrors the backend `GenerateSlug` logic (Go: `steps/slug.go`,
+ * Java: `ApiRequestResourceSlugGenerator`) so the frontend can preview
+ * the exact slug that the server would produce.
+ *
+ * Rules (applied in order):
+ * 1. Convert to lowercase
+ * 2. Replace spaces with hyphens
+ * 3. Strip everything except `a-z`, `0-9`, and `-`
+ * 4. Collapse consecutive hyphens into one
+ * 5. Trim leading / trailing hyphens
+ *
+ * @example
+ * ```ts
+ * generateSlug("My Cool Agent")  // "my-cool-agent"
+ * generateSlug("Acme Corp!")     // "acme-corp"
+ * generateSlug("  --hello-- ")   // "hello"
+ * generateSlug("")               // ""
+ * ```
+ */
+export function generateSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/ /g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Generates a short random suffix suitable for use in resource slugs.
+ *
+ * Returns 8 lowercase hex characters derived from `crypto.randomUUID()`,
+ * providing ~4.3 billion combinations per (org, kind) pair. The output
+ * satisfies the platform slug pattern `^[a-z0-9]+(-[a-z0-9]+)*$`.
+ */
+export function generateSlugSuffix(): string {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+}

package/src/internal/toError.ts

@@ -0,0 +1,19 @@
+/**
+ * Normalize an unknown caught value into an {@link Error}.
+ *
+ * SDK client methods always throw {@link StigmerError} (which extends
+ * `Error`), so the `instanceof` branch covers all normal RPC failures.
+ * The fallback handles edge cases where non-Error values are thrown
+ * (e.g., a rejected promise with a string).
+ *
+ * Preserves the original error identity — callers can still use
+ * `classifyError`, `getUserMessage`, and `getRpcMetadata` from
+ * `@stigmer/sdk` on the returned value.
+ *
+ * @internal
+ */
+export function toError(err: unknown): Error {
+  if (err instanceof Error) return err;
+  if (typeof err === "string") return new Error(err);
+  return new Error("An unexpected error occurred");
+}

package/src/internal/useScrollShadows.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseScrollShadowsReturn {
+  /** Attach to the scrollable container element. */
+  readonly scrollRef: React.RefObject<HTMLDivElement | null>;
+  /** `true` when the container has hidden content above the visible area. */
+  readonly canScrollUp: boolean;
+  /** `true` when the container has hidden content below the visible area. */
+  readonly canScrollDown: boolean;
+}
+
+/**
+ * Tracks whether a scrollable container can scroll up, down, or both.
+ *
+ * Attaches a passive `scroll` listener and a `ResizeObserver` to the
+ * referenced element so the returned booleans stay in sync with both
+ * user scrolling and content-size changes (e.g., new items appended).
+ *
+ * Pair with {@link ScrollFade} to render gradient overlays that signal
+ * hidden content above or below.
+ *
+ * @internal
+ */
+export function useScrollShadows(): UseScrollShadowsReturn {
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const [canScrollUp, setCanScrollUp] = useState(false);
+  const [canScrollDown, setCanScrollDown] = useState(false);
+
+  const update = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    setCanScrollUp(el.scrollTop > 0);
+    setCanScrollDown(el.scrollTop + el.clientHeight < el.scrollHeight - 1);
+  }, []);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+
+    el.addEventListener("scroll", update, { passive: true });
+
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+
+    update();
+
+    return () => {
+      el.removeEventListener("scroll", update);
+      ro.disconnect();
+    };
+  }, [update]);
+
+  return { scrollRef, canScrollUp, canScrollDown };
+}