@stigmer/react 0.0.36 → 0.0.39

package/src/agent-instance/useCreateAgentInstance.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentInstanceInput } from "@stigmer/sdk";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseCreateAgentInstanceReturn {
+  readonly create: (input: AgentInstanceInput) => Promise<AgentInstance>;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `agentInstance.create()` with
+ * loading/error state.
+ *
+ * Creates an AgentInstance resource — a deployed configuration of an
+ * Agent blueprint bound to one or more Environments. The caller
+ * provides an {@link AgentInstanceInput} with `name`, `org`, and
+ * optionally `agentId`, `description`, and `environmentRefs`.
+ *
+ * Returns the full {@link AgentInstance} proto including
+ * server-generated metadata (id, version, timestamps) so callers
+ * can immediately reference the created resource.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**
+ * — agent instances bind Environment resources to Agent blueprints.
+ * For the managed "personal agent instance" convenience, see
+ * {@link usePersonalAgentInstance} which composes this hook with
+ * deterministic naming and label conventions.
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error } = useCreateAgentInstance();
+ *
+ * const instance = await create({
+ *   name: "github-bot-prod",
+ *   org: "acme",
+ *   agentId: "agent-abc123",
+ *   description: "Production GitHub bot",
+ *   environmentRefs: [
+ *     { org: "acme", slug: "prod-credentials" },
+ *   ],
+ * });
+ * ```
+ */
+export function useCreateAgentInstance(): UseCreateAgentInstanceReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: AgentInstanceInput): Promise<AgentInstance> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentInstance.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/agent-instance/usePersonalAgentInstance.ts

@@ -0,0 +1,185 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { ResourceRef } from "@stigmer/sdk";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { useAgentInstanceList } from "./useAgentInstanceList";
+import { buildPersonalInstanceInput } from "./buildPersonalInstanceInput";
+
+const PERSONAL_LABELS: Record<string, string> = {
+  "stigmer.ai/personal": "true",
+};
+
+/**
+ * Input for creating a personal agent instance via
+ * {@link UsePersonalAgentInstanceReturn.getOrCreate}.
+ *
+ * The hook already knows `org` (from its first parameter) and
+ * `agentId` (from its second parameter). This input supplies the
+ * additional context needed only at creation time.
+ */
+export interface GetOrCreatePersonalInstanceInput {
+  /**
+   * The agent's slug, used to derive the instance display name and
+   * unique slug, and the `stigmer.ai/for-agent` label.
+   */
+  readonly agentSlug: string;
+  /**
+   * Reference to the caller's personal environment. The created
+   * instance will link to this environment via `environmentRefs`.
+   */
+  readonly personalEnvironmentRef: ResourceRef;
+}
+
+export interface UsePersonalAgentInstanceReturn {
+  /** The caller's personal agent instance, or `null` if not yet created or still loading. */
+  readonly agentInstance: AgentInstance | null;
+  /** `true` while the initial list query is in-flight. */
+  readonly isLoading: boolean;
+  /** Error from the most recent failed operation (fetch or mutation), or `null`. */
+  readonly error: Error | null;
+  /** Re-query personal agent instances from the server. */
+  readonly refetch: () => void;
+
+  /**
+   * Ensure a personal agent instance exists for this org and agent.
+   *
+   * If one already exists (matched by `agentId`), returns it immediately
+   * without a network call. Otherwise, creates a new instance with:
+   * - Name: `"{agentSlug} Personal"` (display-friendly, may be duplicate)
+   * - Slug: `"{agentSlug}-personal-{random}"` (unique per org)
+   * - Labels: `stigmer.ai/personal: "true"`, `stigmer.ai/for-agent: "{org}/{agentSlug}"`
+   * - Agent binding: the `agentId` passed to the hook
+   * - Environment linkage: `[personalEnvironmentRef]`
+   *
+   * Requires `agentId` to be set on the hook. Throws a descriptive
+   * error if called without it.
+   *
+   * @param input - Agent slug and personal environment reference.
+   * @returns The personal agent instance (existing or newly created).
+   */
+  readonly getOrCreate: (
+    input: GetOrCreatePersonalInstanceInput,
+  ) => Promise<AgentInstance>;
+
+  /** `true` while a `getOrCreate` mutation is in-flight. */
+  readonly isMutating: boolean;
+}
+
+/**
+ * Layer 2 orchestration hook that manages the caller's personal
+ * {@link AgentInstance} for a given organization, optionally scoped
+ * to a specific agent.
+ *
+ * Encapsulates the "personal agent instance" convention: unique slug
+ * per user, labels (`stigmer.ai/personal`, `stigmer.ai/for-agent`),
+ * and the get-or-create lifecycle. Composes {@link useAgentInstanceList}
+ * for declarative reading and the SDK client directly for mutations.
+ *
+ * Pass `null` as `org` to skip all operations (stable no-op).
+ * The `agentId` parameter is optional for read-only use (listing all
+ * personal instances) but required for {@link getOrCreate}.
+ *
+ * This is a Layer 2 **Environment Flow** hook. It provides the managed
+ * "personal agent instance" experience used by the Stigmer Console.
+ * Callers who pre-provision agent instances should use the Layer 1
+ * building-block hook {@link useCreateAgentInstance} directly.
+ *
+ * @example
+ * ```tsx
+ * // Read-only: check if a personal instance exists for an agent
+ * const { agentInstance, isLoading } = usePersonalAgentInstance(
+ *   "acme",
+ *   agent.metadata.id,
+ * );
+ *
+ * // Get-or-create: ensure a personal instance exists
+ * const { getOrCreate, isMutating } = usePersonalAgentInstance(
+ *   "acme",
+ *   agent.metadata.id,
+ * );
+ *
+ * const instance = await getOrCreate({
+ *   agentSlug: "my-github-bot",
+ *   personalEnvironmentRef: { org: "acme", slug: "env-personal-a1b2c3d4" },
+ * });
+ * ```
+ */
+export function usePersonalAgentInstance(
+  org: string | null,
+  agentId?: string,
+): UsePersonalAgentInstanceReturn {
+  const stigmer = useStigmer();
+  const { agentInstances, isLoading, error: listError, refetch } =
+    useAgentInstanceList(org, PERSONAL_LABELS);
+
+  const agentInstance = useMemo(() => {
+    if (agentInstances.length === 0) return null;
+    if (!agentId) return agentInstances[0] ?? null;
+    return (
+      agentInstances.find((ai) => ai.spec?.agentId === agentId) ?? null
+    );
+  }, [agentInstances, agentId]);
+
+  const [isMutating, setIsMutating] = useState(false);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+
+  const agentInstanceRef = useRef(agentInstance);
+  agentInstanceRef.current = agentInstance;
+
+  const error = mutationError ?? listError;
+
+  const getOrCreate = useCallback(
+    async (
+      input: GetOrCreatePersonalInstanceInput,
+    ): Promise<AgentInstance> => {
+      if (agentInstanceRef.current) return agentInstanceRef.current;
+
+      if (!org) {
+        throw new Error(
+          "usePersonalAgentInstance: cannot call getOrCreate when org is null.",
+        );
+      }
+      if (!agentId) {
+        throw new Error(
+          "usePersonalAgentInstance: agentId is required for getOrCreate. " +
+            "Pass the agent's ID as the second argument to the hook.",
+        );
+      }
+
+      setIsMutating(true);
+      setMutationError(null);
+
+      try {
+        const created = await stigmer.agentInstance.create(
+          buildPersonalInstanceInput({
+            org,
+            agentId,
+            agentSlug: input.agentSlug,
+            environmentRef: input.personalEnvironmentRef,
+          }),
+        );
+
+        refetch();
+        return created;
+      } catch (err) {
+        setMutationError(toError(err));
+        throw err;
+      } finally {
+        setIsMutating(false);
+      }
+    },
+    [org, agentId, stigmer, refetch],
+  );
+
+  return {
+    agentInstance,
+    isLoading,
+    error,
+    refetch,
+    getOrCreate,
+    isMutating,
+  };
+}

package/src/attachment/AttachmentChipList.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { AttachmentEntry } from "./useAttachments";
+import { formatFileSize } from "./attachment-utils";
+
+export interface AttachmentChipListProps {
+  /** Attachment entries from {@link useAttachments}. */
+  readonly entries: readonly AttachmentEntry[];
+  /** Remove callback (by entry ID). */
+  readonly onRemove: (id: string) => void;
+  /** Retry callback for failed uploads (by entry ID). */
+  readonly onRetry: (id: string) => void;
+  /** Disables remove and retry actions. */
+  readonly disabled?: boolean;
+  readonly className?: string;
+}
+
+/**
+ * Renders a horizontal list of compact attachment chips showing
+ * filename, size, upload status, and remove/retry actions.
+ *
+ * Designed to sit between the context chips and toolbar in
+ * {@link SessionComposer}, but usable standalone by platform builders
+ * who compose their own attachment UI.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ */
+export function AttachmentChipList({
+  entries,
+  onRemove,
+  onRetry,
+  disabled,
+  className,
+}: AttachmentChipListProps) {
+  if (entries.length === 0) return null;
+
+  return (
+    <div
+      className={cn("flex flex-wrap gap-1.5", className)}
+      role="list"
+      aria-label="Attached files"
+    >
+      {entries.map((entry) => (
+        <AttachmentChip
+          key={entry.id}
+          entry={entry}
+          onRemove={() => onRemove(entry.id)}
+          onRetry={() => onRetry(entry.id)}
+          disabled={disabled}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Individual chip
+// ---------------------------------------------------------------------------
+
+function AttachmentChip({
+  entry,
+  onRemove,
+  onRetry,
+  disabled,
+}: {
+  readonly entry: AttachmentEntry;
+  readonly onRemove: () => void;
+  readonly onRetry: () => void;
+  readonly disabled?: boolean;
+}) {
+  const isError = entry.phase === "error";
+  const isUploading = entry.phase === "uploading";
+
+  return (
+    <span
+      role="listitem"
+      aria-label={`${entry.file.name}, ${formatFileSize(entry.file.size)}${isUploading ? ", uploading" : ""}${isError ? ", upload failed" : ""}`}
+      className={cn(
+        "inline-flex max-w-[200px] items-center gap-1 rounded-md px-2 py-0.5 text-xs",
+        isError
+          ? "border border-destructive/30 bg-destructive/10 text-destructive"
+          : "bg-muted/50 text-foreground",
+        isUploading && "opacity-70",
+      )}
+    >
+      {isUploading && <ChipSpinner />}
+      {isError && <ErrorDot />}
+      {!isUploading && !isError && <FileIcon />}
+
+      <span className="truncate">{entry.file.name}</span>
+
+      <span className="shrink-0 text-[0.6rem] tabular-nums text-muted-foreground">
+        {formatFileSize(entry.file.size)}
+      </span>
+
+      {isError && (
+        <button
+          type="button"
+          onClick={onRetry}
+          disabled={disabled}
+          className="shrink-0 text-[0.6rem] font-medium text-destructive underline hover:text-destructive/80 disabled:pointer-events-none"
+          aria-label={`Retry uploading ${entry.file.name}`}
+        >
+          Retry
+        </button>
+      )}
+
+      <button
+        type="button"
+        onClick={onRemove}
+        disabled={disabled}
+        className="ml-0.5 shrink-0 text-muted-foreground hover:text-destructive disabled:pointer-events-none"
+        aria-label={`Remove ${entry.file.name}`}
+      >
+        <XIcon />
+      </button>
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons — kept minimal and consistent with SessionComposer icons
+// ---------------------------------------------------------------------------
+
+function ChipSpinner() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      className="shrink-0 animate-spin text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M8 2a6 6 0 1 0 6 6" />
+    </svg>
+  );
+}
+
+function ErrorDot() {
+  return (
+    <span
+      className="inline-block h-1.5 w-1.5 shrink-0 rounded-full bg-destructive"
+      aria-hidden="true"
+    />
+  );
+}
+
+function FileIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M8 1H4C3.45 1 3 1.45 3 2V12C3 12.55 3.45 13 4 13H10C10.55 13 11 12.55 11 12V4L8 1Z" />
+      <path d="M8 1V4H11" />
+    </svg>
+  );
+}
+
+function XIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4 4L10 10M10 4L4 10" />
+    </svg>
+  );
+}

package/src/attachment/attachment-utils.ts

@@ -0,0 +1,114 @@
+/**
+ * Maximum attachment size in bytes (10 MB).
+ *
+ * Matches the CLI's `maxAttachmentSize` and the gRPC server's
+ * `MaxRecvMsgSize`. Files exceeding this limit are rejected before
+ * upload to avoid wasting bandwidth on requests that will fail.
+ */
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Extension-to-MIME-type mapping for common file types.
+ *
+ * Used as a fallback when `File.type` is empty or generic. Mirrors
+ * the CLI's `detectContentType` to ensure consistent behavior.
+ */
+const EXTENSION_MIME_MAP: Record<string, string> = {
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".yaml": "application/x-yaml",
+  ".yml": "application/x-yaml",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".tsv": "text/tab-separated-values",
+  ".xml": "application/xml",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".ts": "application/typescript",
+  ".py": "text/x-python",
+  ".go": "text/x-go",
+  ".rs": "text/x-rust",
+  ".java": "text/x-java",
+  ".rb": "text/x-ruby",
+  ".sh": "application/x-sh",
+  ".bash": "application/x-sh",
+  ".sql": "application/sql",
+  ".toml": "application/toml",
+  ".ini": "text/plain",
+  ".cfg": "text/plain",
+  ".conf": "text/plain",
+  ".env": "text/plain",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+};
+
+/**
+ * Detects the MIME content type for a file.
+ *
+ * Prefers the browser-provided `File.type` when available and
+ * non-empty. Falls back to extension-based detection mirroring the
+ * CLI's `detectContentType` function. Returns
+ * `"application/octet-stream"` when neither source yields a result.
+ */
+export function detectContentType(file: File): string {
+  if (file.type && file.type !== "application/octet-stream") {
+    return file.type;
+  }
+
+  const dotIndex = file.name.lastIndexOf(".");
+  if (dotIndex !== -1) {
+    const ext = file.name.slice(dotIndex).toLowerCase();
+    const mapped = EXTENSION_MIME_MAP[ext];
+    if (mapped) return mapped;
+  }
+
+  return "application/octet-stream";
+}
+
+const SIZE_UNITS = ["B", "KB", "MB", "GB"] as const;
+
+/**
+ * Formats a byte count as a human-readable string (e.g., `"2.3 MB"`).
+ *
+ * Uses base-1024 (binary) units with one decimal place, consistent
+ * with {@link formatArtifactSize} in the artifact utilities.
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return "0 B";
+
+  const unitIndex = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    SIZE_UNITS.length - 1,
+  );
+
+  const value = bytes / Math.pow(1024, unitIndex);
+
+  return unitIndex === 0
+    ? `${bytes} B`
+    : `${value.toFixed(1)} ${SIZE_UNITS[unitIndex]}`;
+}
+
+/**
+ * Validates a file against the attachment size limit.
+ *
+ * Returns `null` when valid, or an error message string when the
+ * file exceeds {@link MAX_ATTACHMENT_BYTES}.
+ */
+export function validateAttachmentSize(file: File): string | null {
+  if (file.size > MAX_ATTACHMENT_BYTES) {
+    return `${file.name} exceeds the 10 MB attachment limit (${formatFileSize(file.size)})`;
+  }
+  return null;
+}

package/src/attachment/index.ts

@@ -0,0 +1,17 @@
+export { useAttachments } from "./useAttachments";
+export type {
+  AttachmentPhase,
+  AttachmentEntry,
+  UseAttachmentsOptions,
+  UseAttachmentsReturn,
+} from "./useAttachments";
+
+export { AttachmentChipList } from "./AttachmentChipList";
+export type { AttachmentChipListProps } from "./AttachmentChipList";
+
+export {
+  MAX_ATTACHMENT_BYTES,
+  detectContentType,
+  formatFileSize,
+  validateAttachmentSize,
+} from "./attachment-utils";