@stigmer/react 0.0.36 → 0.0.40

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

@@ -0,0 +1,171 @@
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+
+const PLATFORM_PREFIX = ".stigmer/";
+const PLATFORM_DIR_NAME = ".stigmer";
+
+/**
+ * Result of classifying a tool-call file path against the virtual
+ * platform mount (`.stigmer/`) namespace.
+ */
+export type PathClassification =
+  | { readonly kind: "workspace"; readonly remainder: string }
+  | { readonly kind: "platform"; readonly subpath: string };
+
+/**
+ * Classifies whether a path targets the virtual platform mount
+ * (`.stigmer/skills/`, `.stigmer/inputs/`, etc.) or the workspace.
+ *
+ * Mirrors the Python `classify_platform_path` in
+ * `graphton.core.backends.platform_mount` — same semantics, same
+ * edge-case handling (leading-slash stripping, bare `.stigmer`).
+ */
+export function classifyPath(path: string): PathClassification {
+  const clean = path.replace(/^\/+/, "");
+
+  if (clean.startsWith(PLATFORM_PREFIX)) {
+    return { kind: "platform", subpath: clean.slice(PLATFORM_PREFIX.length) };
+  }
+  if (clean === PLATFORM_DIR_NAME) {
+    return { kind: "platform", subpath: "" };
+  }
+  return { kind: "workspace", remainder: clean };
+}
+
+/**
+ * Constructs a browsable GitHub blob URL from a git clone URL.
+ *
+ * Returns `null` for non-GitHub hosts (graceful degradation — the
+ * caller falls back to copy-to-clipboard).
+ *
+ * @param gitUrl   HTTPS clone URL (e.g. `https://github.com/acme/app.git`)
+ * @param branch   Branch name (may be empty for default branch)
+ * @param commit   Commit SHA (takes precedence over branch when set)
+ * @param relPath  Workspace-relative file path
+ */
+export function resolveGitBrowseUrl(
+  gitUrl: string,
+  branch: string,
+  commit: string,
+  relPath: string,
+): string | null {
+  let url: URL;
+  try {
+    url = new URL(gitUrl);
+  } catch {
+    return null;
+  }
+
+  if (url.hostname !== "github.com") return null;
+
+  // Strip trailing `.git` and leading/trailing slashes from pathname
+  const repoPath = url.pathname.replace(/\.git$/, "").replace(/^\/|\/$/g, "");
+  if (!repoPath) return null;
+
+  const ref = commit || branch || "HEAD";
+  const cleanRelPath = relPath.replace(/^\/+/, "");
+
+  return `https://github.com/${repoPath}/blob/${ref}/${cleanRelPath}`;
+}
+
+/**
+ * Resolved action for a file path. Consumed by {@link FilePathLink}
+ * 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 };
+
+/**
+ * Resolves a tool-call file path to a user action.
+ *
+ * Resolution strategy (mirrors the CLI's `buildHyperlinkedPath`):
+ *
+ * 1. **Platform paths** (`.stigmer/` prefix) → copy raw path.
+ * 2. **Workspace paths** → match against workspace entries:
+ *    - Single entry: treat path as relative to that entry.
+ *    - Multiple entries: match first path segment against entry names.
+ *      Unmatched segments fall back to the first entry (optimistic —
+ *      single-workspace sessions are the common case).
+ * 3. **Git source** → construct GitHub blob URL.
+ * 4. **Local source** → join with absolute local path for copy.
+ * 5. **Fallback** → copy the raw path.
+ */
+export function resolvePathAction(
+  path: string,
+  workspaceEntries: readonly WorkspaceEntry[],
+): ResolvedPathAction {
+  if (!path) {
+    return { action: "copy", value: path, tooltip: "Copy path" };
+  }
+
+  const classification = classifyPath(path);
+
+  if (classification.kind === "platform") {
+    return { action: "copy", value: path, tooltip: "Copy path" };
+  }
+
+  const { remainder } = classification;
+  if (workspaceEntries.length === 0) {
+    return { action: "copy", value: path, tooltip: "Copy path" };
+  }
+
+  const { entry, relPath } = matchWorkspaceEntry(remainder, workspaceEntries);
+  const source = entry.source?.source;
+
+  if (source?.case === "gitRepo") {
+    const url = resolveGitBrowseUrl(
+      source.value.url,
+      source.value.branch,
+      source.value.commit,
+      relPath,
+    );
+    if (url) {
+      return { action: "link", url, tooltip: "Open on GitHub" };
+    }
+  }
+
+  if (source?.case === "localPath") {
+    const abs = joinLocalPath(source.value.path, relPath);
+    return { action: "copy", value: abs, tooltip: "Copy path" };
+  }
+
+  return { action: "copy", value: path, tooltip: "Copy path" };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches a workspace-relative path against entries. With a single
+ * entry the path is used as-is. With multiple entries the first path
+ * segment is tested against entry names; unmatched paths fall back to
+ * the first entry (same strategy as the CLI).
+ */
+function matchWorkspaceEntry(
+  relPath: string,
+  entries: readonly WorkspaceEntry[],
+): { entry: WorkspaceEntry; relPath: string } {
+  if (entries.length === 1) {
+    return { entry: entries[0], relPath };
+  }
+
+  const slashIdx = relPath.indexOf("/");
+  const firstSegment = slashIdx >= 0 ? relPath.slice(0, slashIdx) : relPath;
+
+  for (const entry of entries) {
+    if (entry.name === firstSegment) {
+      const rest = slashIdx >= 0 ? relPath.slice(slashIdx + 1) : "";
+      return { entry, relPath: rest };
+    }
+  }
+
+  return { entry: entries[0], relPath };
+}
+
+function joinLocalPath(base: string, rel: string): string {
+  if (!rel) return base;
+  const cleanBase = base.replace(/\/+$/, "");
+  const cleanRel = rel.replace(/^\/+/, "");
+  return `${cleanBase}/${cleanRel}`;
+}

package/src/execution/index.ts

@@ -0,0 +1,97 @@
+export { useCreateAgentExecution } from "./useCreateAgentExecution";
+export type {
+  CreateAgentExecutionInput,
+  CreateAgentExecutionResult,
+  UseCreateAgentExecutionReturn,
+} from "./useCreateAgentExecution";
+
+export { isTerminalPhase } from "./execution-phases";
+
+export { useExecutionStream } from "./useExecutionStream";
+export type { UseExecutionStreamReturn } from "./useExecutionStream";
+
+export { useExecutionUsage, aggregateUsage } from "./useExecutionUsage";
+export type { UseExecutionUsageReturn } from "./useExecutionUsage";
+
+export { useExecutionArtifacts } from "./useExecutionArtifacts";
+export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts";
+
+export { useArtifactContent } from "./useArtifactContent";
+export type { UseArtifactContentReturn } from "./useArtifactContent";
+
+export {
+  isTextArtifact,
+  isArtifactExpired,
+  formatArtifactSize,
+  getArtifactExtension,
+} from "./artifact-utils";
+
+export { ExecutionPhaseBadge } from "./ExecutionPhaseBadge";
+export type { ExecutionPhaseBadgeProps } from "./ExecutionPhaseBadge";
+
+export { ToolCallGroup } from "./ToolCallGroup";
+export type { ToolCallGroupProps } from "./ToolCallGroup";
+
+export { ToolCallDetail, formatDuration } from "./ToolCallDetail";
+export type { ToolCallDetailProps } from "./ToolCallDetail";
+
+export { ToolCallItem } from "./ToolCallItem";
+export type { ToolCallItemProps } from "./ToolCallItem";
+
+export { SubAgentSection } from "./SubAgentSection";
+export type { SubAgentSectionProps } from "./SubAgentSection";
+
+export { MessageEntry } from "./MessageEntry";
+export type { MessageEntryProps } from "./MessageEntry";
+
+export { MessageThread } from "./MessageThread";
+export type { MessageThreadProps } from "./MessageThread";
+
+export { FollowUpInput } from "./FollowUpInput";
+export type { FollowUpInputProps } from "./FollowUpInput";
+
+export { ExecutionProgress } from "./ExecutionProgress";
+export type { ExecutionProgressProps } from "./ExecutionProgress";
+
+export { ExecutionCostSummary, formatCost, formatTokenCount } from "./ExecutionCostSummary";
+export type { ExecutionCostSummaryProps } from "./ExecutionCostSummary";
+
+export { useSubmitApproval } from "./useSubmitApproval";
+export type { UseSubmitApprovalReturn } from "./useSubmitApproval";
+
+export { ApprovalCard } from "./ApprovalCard";
+export type { ApprovalCardProps } from "./ApprovalCard";
+
+export { ArtifactCard } from "./ArtifactCard";
+export type { ArtifactCardProps } from "./ArtifactCard";
+
+export { ArtifactPreviewModal } from "./ArtifactPreviewModal";
+export type { ArtifactPreviewModalProps } from "./ArtifactPreviewModal";
+
+export { ArtifactsWidget } from "./ArtifactsWidget";
+export type { ArtifactsWidgetProps } from "./ArtifactsWidget";
+
+export {
+  resolveToolCategory,
+  extractPrimaryArg,
+  extractPrimaryArgFromPreview,
+} from "./tool-categories";
+export type { ToolCategory, ToolCategoryInfo } from "./tool-categories";
+
+export { FilePathLink } from "./FilePathLink";
+export type { FilePathLinkProps } from "./FilePathLink";
+
+export { FilePathContext } from "./FilePathContext";
+export type { FilePathContextValue } from "./FilePathContext";
+
+export { classifyPath, resolveGitBrowseUrl, resolvePathAction } from "./file-path-resolver";
+export type { PathClassification, ResolvedPathAction } from "./file-path-resolver";
+
+export { useSessionVariables } from "./useSessionVariables";
+export type {
+  SessionVariableEntry,
+  UseSessionVariablesReturn,
+} from "./useSessionVariables";
+
+export { SessionVariablesInput } from "./SessionVariablesInput";
+export type { SessionVariablesInputProps } from "./SessionVariablesInput";

package/src/execution/tool-categories.ts

@@ -0,0 +1,171 @@
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
+
+/**
+ * Discriminated tool categories for type-aware rendering.
+ *
+ * Mirrors the CLI's `toolDisplayMap` in
+ * `client-apps/cli/pkg/toolrender/render.go`.
+ */
+export type ToolCategory =
+  | "shell"
+  | "read"
+  | "write"
+  | "edit"
+  | "delete"
+  | "search"
+  | "list"
+  | "think"
+  | "sub-agent"
+  | "unknown";
+
+export interface ToolCategoryInfo {
+  readonly category: ToolCategory;
+  readonly label: string;
+  readonly primaryArgField: string;
+  readonly fallbackArgFields: readonly string[];
+}
+
+interface ToolDisplayEntry {
+  readonly category: ToolCategory;
+  readonly label: string;
+  readonly primaryField: string;
+  readonly fallbackFields?: readonly string[];
+}
+
+const TOOL_DISPLAY_MAP: ReadonlyMap<string, ToolDisplayEntry> = new Map([
+  ["shell",           { category: "shell",     label: "Shell",     primaryField: "command" }],
+  ["bash",            { category: "shell",     label: "Shell",     primaryField: "command" }],
+  ["execute",         { category: "shell",     label: "Execute",   primaryField: "command" }],
+  ["execute_command", { category: "shell",     label: "Shell",     primaryField: "command" }],
+  ["run_command",     { category: "shell",     label: "Shell",     primaryField: "command" }],
+  ["terminal",        { category: "shell",     label: "Shell",     primaryField: "command" }],
+
+  ["read",            { category: "read",      label: "Read",      primaryField: "path",    fallbackFields: ["file_path", "file"] }],
+  ["read_file",       { category: "read",      label: "Read",      primaryField: "path",    fallbackFields: ["file_path", "file"] }],
+
+  ["write",           { category: "write",     label: "Write",     primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+  ["write_file",      { category: "write",     label: "Write",     primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+  ["create_file",     { category: "write",     label: "Create",    primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+  ["overwrite_file",  { category: "write",     label: "Write",     primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+
+  ["edit",            { category: "edit",      label: "Edit",      primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+  ["edit_file",       { category: "edit",      label: "Edit",      primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+
+  ["delete_file",     { category: "delete",    label: "Delete",    primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+  ["remove_file",     { category: "delete",    label: "Delete",    primaryField: "path",    fallbackFields: ["file_path", "file", "filename"] }],
+
+  ["glob",            { category: "search",    label: "Find",      primaryField: "pattern" }],
+  ["grep",            { category: "search",    label: "Search",    primaryField: "pattern" }],
+
+  ["list_directory",  { category: "list",      label: "List",      primaryField: "path" }],
+  ["ls",              { category: "list",      label: "List",      primaryField: "path" }],
+
+  ["think",           { category: "think",     label: "Thinking",  primaryField: "thought" }],
+
+  ["task",            { category: "sub-agent", label: "Sub-agent", primaryField: "description", fallbackFields: ["prompt"] }],
+]);
+
+/**
+ * Resolves a tool name to its category metadata for type-aware
+ * rendering. Returns a stable `"unknown"` entry for unrecognized
+ * tools using the raw tool name as the label.
+ */
+export function resolveToolCategory(toolName: string): ToolCategoryInfo {
+  const entry = TOOL_DISPLAY_MAP.get(toolName);
+  if (entry) {
+    return {
+      category: entry.category,
+      label: entry.label,
+      primaryArgField: entry.primaryField,
+      fallbackArgFields: entry.fallbackFields ?? [],
+    };
+  }
+  return {
+    category: "unknown",
+    label: toolName,
+    primaryArgField: "",
+    fallbackArgFields: [],
+  };
+}
+
+function extractArgValue(
+  args: JsonObject | undefined,
+  primary: string,
+  fallbacks: readonly string[],
+): string | null {
+  if (!args) return null;
+
+  const tryField = (field: string): string | null => {
+    const val = args[field];
+    if (typeof val === "string" && val.length > 0) return val;
+    return null;
+  };
+
+  if (primary) {
+    const v = tryField(primary);
+    if (v) return v;
+  }
+
+  for (const fb of fallbacks) {
+    const v = tryField(fb);
+    if (v) return v;
+  }
+
+  return null;
+}
+
+/**
+ * Extracts the most relevant argument value from a tool call
+ * based on its category (command for shell tools, path for file
+ * tools, pattern for search tools, etc.).
+ *
+ * Returns `null` when the tool is unknown and has no arguments,
+ * or when the expected argument fields are missing.
+ */
+export function extractPrimaryArg(toolCall: ToolCall): string | null {
+  const info = resolveToolCategory(toolCall.name);
+  const result = extractArgValue(
+    toolCall.args,
+    info.primaryArgField,
+    info.fallbackArgFields,
+  );
+
+  if (result) return result;
+
+  if (info.category === "unknown" && toolCall.args) {
+    const keys = Object.keys(toolCall.args);
+    if (keys.length > 0) {
+      const val = toolCall.args[keys[0]];
+      if (typeof val === "string") return val;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extracts the primary argument value from a JSON string
+ * (typically `PendingApproval.argsPreview`). Returns `null` if
+ * parsing fails or the expected field is not found.
+ */
+export function extractPrimaryArgFromPreview(
+  toolName: string,
+  argsPreview: string,
+): string | null {
+  if (!argsPreview) return null;
+
+  try {
+    const parsed = JSON.parse(argsPreview);
+    if (typeof parsed !== "object" || parsed === null) return null;
+
+    const info = resolveToolCategory(toolName);
+    return extractArgValue(
+      parsed as JsonObject,
+      info.primaryArgField,
+      info.fallbackArgFields,
+    );
+  } catch {
+    return null;
+  }
+}

package/src/execution/useArtifactContent.ts

@@ -0,0 +1,156 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactContentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+
+export interface UseArtifactContentReturn {
+  /**
+   * Decoded text content of the artifact, or `null` when:
+   * - Fetching is skipped (`executionId` or `storageKey` is `null`)
+   * - The request is in-flight
+   * - The request failed
+   */
+  readonly content: string | null;
+
+  /**
+   * Detected content type (e.g., `"text/yaml"`, `"text/plain"`).
+   * `null` before the first successful fetch.
+   */
+  readonly contentType: string | null;
+
+  /**
+   * Whether the returned content was truncated by the server's
+   * `max_bytes` limit. When `true`, the full artifact should be
+   * downloaded via `getArtifactDownloadUrl` instead.
+   */
+  readonly isTruncated: boolean;
+
+  /** `true` while the content request is in-flight. */
+  readonly isLoading: boolean;
+
+  /** Error message from the last failed attempt, or `null` when healthy. */
+  readonly error: string | null;
+
+  /**
+   * Re-fetch the artifact content. Uses the `fetchKey` counter pattern
+   * consistent with `refetch()` in other SDK hooks.
+   */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the text content of a single execution artifact
+ * via `stigmer.agentExecution.getArtifactContent()`.
+ *
+ * The server reads the artifact from R2 and returns the bytes through the
+ * Stigmer API, eliminating CORS concerns for SDK consumers who need to
+ * read artifact content programmatically (YAML detection, preview
+ * rendering, resource type identification).
+ *
+ * Pass `null` for either parameter to skip fetching — consistent with
+ * the `useExecutionStream(null)` convention. The caller controls when
+ * to fetch based on artifact metadata (e.g., only for text artifacts
+ * below a size threshold):
+ *
+ * ```tsx
+ * const shouldFetch = isTextArtifact(artifact) && Number(artifact.sizeBytes) < MAX_SIZE;
+ * const { content } = useArtifactContent(
+ *   shouldFetch ? executionId : null,
+ *   shouldFetch ? artifact.storageKey : null,
+ * );
+ * ```
+ *
+ * For directory artifacts (ZIPs), pass `entryPath` to extract a specific
+ * file from the archive instead of returning the raw ZIP bytes:
+ *
+ * ```tsx
+ * const { content } = useArtifactContent(executionId, storageKey, "SKILL.md");
+ * ```
+ *
+ * The server enforces a content size limit (default 512 KB). Content
+ * exceeding this limit is truncated — check `isTruncated` and offer
+ * a full download via the pre-signed URL for large artifacts.
+ *
+ * The returned `content` is decoded from UTF-8 bytes. For binary
+ * artifacts, use `getArtifactDownloadUrl` instead of this hook.
+ *
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ * @param storageKey - Storage key from `ExecutionArtifact.storageKey`, or `null` to skip.
+ * @param entryPath - For directory artifacts: relative path of a file within
+ *   the archive to extract. `null` returns the full artifact (existing behavior).
+ *
+ * @see useExecutionArtifacts — extracts artifact metadata from an execution
+ * @see isTextArtifact — heuristic for whether content is fetchable as text
+ */
+export function useArtifactContent(
+  executionId: string | null,
+  storageKey: string | null,
+  entryPath?: string | null,
+): UseArtifactContentReturn {
+  const stigmer = useStigmer();
+
+  const [content, setContent] = useState<string | null>(null);
+  const [contentType, setContentType] = useState<string | null>(null);
+  const [isTruncated, setIsTruncated] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!executionId || !storageKey) {
+      setContent(null);
+      setContentType(null);
+      setIsTruncated(false);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.agentExecution
+      .getArtifactContent(
+        create(GetArtifactContentRequestSchema, {
+          executionId,
+          storageKey,
+          ...(entryPath ? { entryPath } : {}),
+        }),
+      )
+      .then(
+        (result) => {
+          if (cancelled.current) return;
+
+          const decoded = new TextDecoder().decode(result.content);
+          setContent(decoded);
+          setContentType(result.contentType || null);
+          setIsTruncated(result.truncated);
+          setIsLoading(false);
+        },
+        (err) => {
+          if (cancelled.current) return;
+
+          setError(
+            err instanceof Error
+              ? err.message
+              : "Failed to load artifact content",
+          );
+          setContent(null);
+          setContentType(null);
+          setIsTruncated(false);
+          setIsLoading(false);
+        },
+      );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [executionId, storageKey, entryPath, stigmer, fetchKey]);
+
+  return { content, contentType, isTruncated, isLoading, error, refetch };
+}