@stigmer/react 3.1.3 → 3.1.5

package/src/execution/index.ts

@@ -169,7 +169,11 @@ export { MessageEntry } from "./MessageEntry.js";
 export type { MessageEntryProps } from "./MessageEntry.js";
 
 export { MessageThread } from "./MessageThread.js";
-export type { MessageThreadProps, ThreadContentColumn } from "./MessageThread.js";
+export type {
+  MessageThreadProps,
+  MessageThreadSlots,
+  ThreadContentColumn,
+} from "./MessageThread.js";
 
 export { ThreadSkeleton } from "./ThreadSkeleton.js";
 export type { ThreadSkeletonProps } from "./ThreadSkeleton.js";
@@ -182,11 +186,12 @@ export type { ExecutionProgressProps } from "./ExecutionProgress.js";
 
 export {
   TodoList,
+  TodoRow,
   TodoInProgressIcon,
   findActiveTodo,
   todoCompletionSummary,
 } from "./TodoList.js";
-export type { TodoListProps } from "./TodoList.js";
+export type { TodoListProps, TodoRowProps } from "./TodoList.js";
 
 export { TodoCard } from "./TodoCard.js";
 export type { TodoCardProps } from "./TodoCard.js";
@@ -204,6 +209,7 @@ export {
   deriveEffectiveVerdicts,
   changeForRowPath,
   fileReviewRowState,
+  fileReviewRowChange,
 } from "./file-review-status.js";
 export type {
   FileReviewability,
@@ -239,15 +245,31 @@ export type { FileChangeProgressBarProps } from "./FileChangeProgressBar.js";
 export { ApprovalContext, useApproval } from "./ApprovalContext.js";
 export type { ApprovalContextValue, UseApprovalResult } from "./ApprovalContext.js";
 
-export { FileReviewContext, useFileReviewRowState } from "./FileReviewContext.js";
+export {
+  FileReviewContext,
+  useFileReviewRowState,
+  useFileReviewRowChange,
+} from "./FileReviewContext.js";
 export type { FileReviewContextValue } from "./FileReviewContext.js";
 
-export { ArtifactCard } from "./ArtifactCard.js";
-export type { ArtifactCardProps } from "./ArtifactCard.js";
+export { ArtifactRow } from "./ArtifactRow.js";
+export type { ArtifactRowProps } from "./ArtifactRow.js";
 
 export { ArtifactContentRenderer } from "./ArtifactContentRenderer.js";
 export type { ArtifactContentRendererProps } from "./ArtifactContentRenderer.js";
 
+export { ArtifactContentBody } from "./ArtifactContentBody.js";
+export type { ArtifactContentBodyProps } from "./ArtifactContentBody.js";
+
+export { ArtifactDocument } from "./ArtifactDocument.js";
+export type { ArtifactDocumentProps } from "./ArtifactDocument.js";
+
+export { useArtifactInspection } from "./useArtifactInspection.js";
+export type {
+  ArtifactInspection,
+  UseArtifactInspectionOptions,
+} from "./useArtifactInspection.js";
+
 export { ArtifactPreviewContent, ArtifactPreviewModal } from "./ArtifactPreviewModal.js";
 export type { ArtifactPreviewContentProps, ArtifactPreviewModalProps } from "./ArtifactPreviewModal.js";
 

package/src/execution/useArtifactContent.ts

@@ -100,6 +100,11 @@ export interface UseArtifactContentReturn {
  *   When the same file is overwritten during execution, the `storageKey` stays
  *   stable but `contentHash` changes, triggering a re-fetch so the UI never
  *   shows stale content. Pass `undefined` or omit for backwards compatibility.
+ * @param cacheKey - Optional cross-mount cache key (DD-014). When set, a remount
+ *   with the same key renders the previously-fetched content instantly and
+ *   refetches in the background (no skeleton flash) — used by the artifact
+ *   document so switching back to a recently-viewed tab is instant. Omit for the
+ *   default fetch-on-mount behavior (card / modal / plan callers are unchanged).
  *
  * @example
  * ```tsx
@@ -142,6 +147,7 @@ export function useArtifactContent(
   storageKey: string | null,
   entryPath?: string | null,
   contentHash?: string,
+  cacheKey?: string,
 ): UseArtifactContentReturn {
   const stigmer = useStigmer();
 
@@ -164,6 +170,7 @@ export function useArtifactContent(
       : null,
     [executionId, storageKey, entryPath, contentHash, stigmer],
     EMPTY_ARTIFACT,
+    cacheKey ? { cacheKey } : undefined,
   );
 
   return {

package/src/execution/useArtifactInspection.ts

@@ -0,0 +1,252 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { useArtifactContent } from "./useArtifactContent.js";
+import { isTextArtifact } from "./artifact-utils.js";
+import { useDetectStigmerResource } from "../library/useDetectStigmerResource.js";
+import { useDetectSkillPackage } from "../library/useDetectSkillPackage.js";
+import type { SkillPackageDetection } from "../library/detect-skill-package.js";
+import {
+  useApplyResource,
+  type ApplyResourceResult,
+} from "../library/useApplyResource.js";
+
+const COPIED_FEEDBACK_MS = 2000;
+
+/** Options for {@link useArtifactInspection}. */
+export interface UseArtifactInspectionOptions {
+  /**
+   * Cross-mount cache key for the content fetch (DD-014). Set it so a remount
+   * with the same key renders the previously-fetched content instantly and
+   * refetches in the background — the artifact document passes it so switching
+   * back to a recently-viewed tab is instant. Omit for fetch-on-mount (the
+   * modal, which resets on every open).
+   */
+  readonly cacheKey?: string;
+  /**
+   * Called after a resource is successfully applied or a skill package pushed.
+   * The consumer uses it for post-apply behavior (toast, navigate to Library).
+   */
+  readonly onApplied?: (result: ApplyResourceResult) => void;
+}
+
+/**
+ * Everything a chrome (the modal action bar, the document toolbar, the content
+ * body) needs to inspect and act on one artifact: fetched content, resource
+ * detection, the Apply/Push action, and clipboard copy.
+ */
+export interface ArtifactInspection {
+  /** Decoded text content, or `null` (directory / binary / loading / error). */
+  readonly content: string | null;
+  /** Server-detected content type, or `null`. */
+  readonly contentType: string | null;
+  /** Whether the fetched content was truncated by the server's size cap. */
+  readonly isTruncated: boolean;
+  /** `true` while the content request is in-flight (first load). */
+  readonly isLoading: boolean;
+  /** Content-fetch error, or `null`. */
+  readonly error: Error | null;
+  /** Re-fetch the artifact content. */
+  readonly refetch: () => void;
+
+  /** Whether the artifact is a directory (skill package candidate). */
+  readonly isDirectory: boolean;
+  /** Skill-package detection for directory artifacts. */
+  readonly skillDetection: SkillPackageDetection;
+
+  /** `true` when the artifact is a recognized Stigmer resource or skill. */
+  readonly isDetected: boolean;
+  /** `true` while detection is still resolving (content / skill fetch). */
+  readonly isDetecting: boolean;
+  /** Detection badge label (`"Agent detected"`, `"Skill · N files"`), or `null`. */
+  readonly detectionLabel: string | null;
+
+  /** Apply/Push CTA label (`"Apply to org"`, `"Push Skill to org"`), or `null`. */
+  readonly ctaLabel: string | null;
+  /** Apply the detected resource / push the detected skill. */
+  readonly apply: () => Promise<void>;
+  /** `true` while an apply/push is in-flight. */
+  readonly isApplying: boolean;
+  /** The successful apply result, or `null`. */
+  readonly applyResult: ApplyResourceResult | null;
+  /** Apply/push error, or `null`. */
+  readonly applyError: Error | null;
+
+  /** Copy the in-memory content to the clipboard. No-op without content. */
+  readonly copy: () => void;
+  /** `true` for a short window after a successful copy. */
+  readonly copied: boolean;
+}
+
+/**
+ * Headless behavior hook consolidating the artifact inspect-and-act pipeline
+ * that was previously inlined per artifact surface: content fetch,
+ * Agent/McpServer YAML detection, skill-package detection, the Apply/Push
+ * mutation, and in-memory clipboard copy.
+ *
+ * It is the single writer of this pipeline's derived state, consumed by every
+ * artifact chrome — the modal action bar and the editor-area
+ * `ArtifactDocument` toolbar (DD-003 headless-first). Because there is exactly
+ * one place computing `detectionLabel` / `ctaLabel` / the apply flow, the two
+ * surfaces cannot drift.
+ *
+ * All four underlying hooks are called unconditionally with null-gated
+ * arguments (their documented skip contract), so this composition is
+ * React-rules-clean regardless of the artifact kind.
+ *
+ * @param artifact - The artifact to inspect.
+ * @param executionId - Execution that produced it (content + skill fetching).
+ * @param org - Organization for the "Apply to [org]" / "Push Skill to [org]" CTA.
+ * @param options - {@link UseArtifactInspectionOptions}.
+ */
+export function useArtifactInspection(
+  artifact: ExecutionArtifact,
+  executionId: string,
+  org: string,
+  options?: UseArtifactInspectionOptions,
+): ArtifactInspection {
+  const isDirectory = artifact.kind === ExecutionArtifactKind.DIRECTORY;
+  const canFetchContent = !isDirectory && isTextArtifact(artifact);
+
+  const {
+    content,
+    contentType,
+    isTruncated,
+    isLoading,
+    error,
+    refetch,
+  } = useArtifactContent(
+    canFetchContent ? executionId : null,
+    canFetchContent ? artifact.storageKey : null,
+    undefined,
+    artifact.contentHash || undefined,
+    options?.cacheKey,
+  );
+
+  const yamlDetection = useDetectStigmerResource(
+    canFetchContent ? content : null,
+  );
+
+  const { detection: skillDetection, isLoading: isSkillLoading } =
+    useDetectSkillPackage(
+      isDirectory ? artifact : null,
+      isDirectory ? executionId : null,
+    );
+
+  const isDetected = yamlDetection.detected || skillDetection.detected;
+  const isDetecting =
+    (canFetchContent && isLoading) || (isDirectory && isSkillLoading);
+
+  let detectionLabel: string | null = null;
+  if (yamlDetection.detected) {
+    detectionLabel = `${yamlDetection.displayName} detected`;
+  } else if (skillDetection.detected) {
+    const count = skillDetection.fileCount;
+    detectionLabel = `Skill \u00B7 ${count} ${count === 1 ? "file" : "files"}`;
+  }
+
+  let ctaLabel: string | null = null;
+  if (yamlDetection.detected) {
+    ctaLabel = `Apply to ${org}`;
+  } else if (skillDetection.detected) {
+    ctaLabel = `Push Skill to ${org}`;
+  }
+
+  // --- Apply / Push ---------------------------------------------------------
+
+  const { applyYamlResource, pushSkillPackage, isApplying, error: applyError, clearError } =
+    useApplyResource();
+  const [applyResult, setApplyResult] = useState<ApplyResourceResult | null>(
+    null,
+  );
+  const onApplied = options?.onApplied;
+
+  const apply = useCallback(async () => {
+    clearError();
+    try {
+      let result: ApplyResourceResult;
+      if (yamlDetection.detected && content) {
+        result = await applyYamlResource(content, org);
+      } else if (skillDetection.detected) {
+        result = await pushSkillPackage({
+          org,
+          executionId,
+          storageKey: artifact.storageKey,
+        });
+      } else {
+        return;
+      }
+      setApplyResult(result);
+      onApplied?.(result);
+    } catch {
+      // error state is owned by useApplyResource
+    }
+  }, [
+    yamlDetection.detected,
+    skillDetection.detected,
+    content,
+    org,
+    executionId,
+    artifact.storageKey,
+    applyYamlResource,
+    pushSkillPackage,
+    clearError,
+    onApplied,
+  ]);
+
+  // --- Copy -----------------------------------------------------------------
+
+  const [copied, setCopied] = useState(false);
+  const copy = useCallback(() => {
+    if (!content) return;
+    void navigator.clipboard.writeText(content).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), COPIED_FEEDBACK_MS);
+    });
+  }, [content]);
+
+  return useMemo(
+    () => ({
+      content,
+      contentType,
+      isTruncated,
+      isLoading,
+      error,
+      refetch,
+      isDirectory,
+      skillDetection,
+      isDetected,
+      isDetecting,
+      detectionLabel,
+      ctaLabel,
+      apply,
+      isApplying,
+      applyResult,
+      applyError,
+      copy,
+      copied,
+    }),
+    [
+      content,
+      contentType,
+      isTruncated,
+      isLoading,
+      error,
+      refetch,
+      isDirectory,
+      skillDetection,
+      isDetected,
+      isDetecting,
+      detectionLabel,
+      ctaLabel,
+      apply,
+      isApplying,
+      applyResult,
+      applyError,
+      copy,
+      copied,
+    ],
+  );
+}

package/src/execution/useCreateAgentExecution.ts

@@ -93,6 +93,17 @@ export interface CreateAgentExecutionInput {
    * Populated by the drag-to-reference feature in SessionComposer.
    */
   readonly workspaceFileRefs?: string[];
+  /**
+   * ID of the execution this one supersedes via edit-and-resubmit.
+   *
+   * Set when the user stopped an in-flight turn, edited its message, and
+   * resubmitted. Chat threads hide the superseded execution so the edited
+   * message replaces the original in place; history surfaces keep the full
+   * record. Maps to `AgentExecutionSpec.supersedes_execution_id`.
+   *
+   * Display-level only — the runner does not rewind model context.
+   */
+  readonly supersedesExecutionId?: string;
 }
 
 /** Resolved output of {@link UseCreateAgentExecutionReturn.create}. */
@@ -199,6 +210,7 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
           runtimeEnv: input.runtimeEnv,
           attachments: input.attachments,
           workspaceFileRefs: input.workspaceFileRefs,
+          supersedesExecutionId: input.supersedesExecutionId,
         });
 
         return {

package/src/github/__tests__/useGitHubFileReader.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { renderHook } from "@testing-library/react";
 import { useGitHubFileReader } from "../useGitHubFileReader";
+import { WorkspaceFileNotFoundError } from "../../workspace/WorkspaceFileReader";
 import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
 
 function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
@@ -120,11 +121,43 @@ describe("useGitHubFileReader", () => {
     );
   });
 
-  it("throws on a non-OK response (404 = failed to load, not unsupported)", async () => {
+  it("throws the typed WorkspaceFileNotFoundError on a 404", async () => {
     vi.mocked(globalThis.fetch).mockResolvedValue(new Response("nope", { status: 404 }));
 
     const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
-    await expect(result.current!(gitEntry(), "missing.ts")).rejects.toThrow("HTTP 404");
+    await expect(result.current!(gitEntry(), "missing.ts")).rejects.toThrow(
+      WorkspaceFileNotFoundError,
+    );
+  });
+
+  it("throws a generic error (not the typed not-found) on other non-OK responses", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(new Response("boom", { status: 500 }));
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const error = await result.current!(gitEntry(), "src/index.ts").then(
+      () => null,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("HTTP 500");
+    expect(error).not.toBeInstanceOf(WorkspaceFileNotFoundError);
+  });
+
+  it("reads at readRef in preference to gitBranch when both are set", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 1, content: b64("x"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await result.current!(
+      gitEntry({ gitBranch: "main", readRef: "abc123def456" }),
+      "notes.md",
+    );
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("?ref=abc123def456"),
+      expect.anything(),
+    );
   });
 
   it("throws when the path is a directory (Contents API returns an array)", async () => {

package/src/github/__tests__/useGitHubTreeLister.test.ts

@@ -148,6 +148,20 @@ describe("useGitHubTreeLister", () => {
     );
   });
 
+  it("lists at readRef in preference to gitBranch when both are set", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    await result.current!(gitEntry({ gitBranch: "main", readRef: "abc123def456" }));
+
+    expect(vi.mocked(globalThis.fetch)).toHaveBeenCalledWith(
+      expect.stringContaining("/git/trees/abc123def456?"),
+      expect.anything(),
+    );
+  });
+
   it("encodes branch names with special characters", async () => {
     vi.mocked(globalThis.fetch).mockResolvedValue(
       new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),

package/src/github/useGitHubFileReader.ts

@@ -2,9 +2,10 @@
 
 import { useCallback } from "react";
 import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
-import type {
-  WorkspaceFileContent,
-  WorkspaceFileReader,
+import {
+  WorkspaceFileNotFoundError,
+  type WorkspaceFileContent,
+  type WorkspaceFileReader,
 } from "../workspace/WorkspaceFileReader.js";
 import { base64ToBytes, normalizeGitHubContent } from "./decodeGitHubContent.js";
 import { parseGitUrl } from "./parseGitUrl.js";
@@ -58,7 +59,9 @@ function encodePath(path: string): string {
  *   (non-git entry, missing/unparseable URL) — the "unsupported here" state.
  * - **Throws** on a real failure: a non-OK response, or a directory path
  *   (which the Contents API returns as a JSON array). Consumers surface these
- *   as an error, distinct from the null "unsupported" state.
+ *   as an error, distinct from the null "unsupported" state. A 404 throws the
+ *   typed {@link WorkspaceFileNotFoundError} so consumers can fall back to
+ *   session-captured content for files not yet pushed to the ref.
  *
  * @example
  * ```tsx
@@ -80,14 +83,24 @@ export function useGitHubFileReader(
       const parsed = parseGitUrl(entry.gitUrl);
       if (!parsed) return null;
 
-      const branch = entry.gitBranch || "main";
+      // readRef (the session's write-back commit SHA, when one exists) wins
+      // over the configured branch: agent-created files live on the pushed
+      // write-back commit, not the base branch. The Contents API accepts a
+      // branch name or a commit SHA interchangeably as `ref`.
+      const ref = entry.readRef || entry.gitBranch || "main";
       const url =
         `${GITHUB_API}/${parsed.owner}/${parsed.repo}/contents/${encodePath(path)}` +
-        `?ref=${encodeURIComponent(branch)}`;
+        `?ref=${encodeURIComponent(ref)}`;
 
       const resp = await fetch(url, {
         headers: { Authorization: `Bearer ${token}` },
       });
+      // 404 is typed: a file that isn't at this ref (yet) is an expected,
+      // recoverable state — e.g. an agent-created file whose write-back
+      // hasn't pushed — that consumers handle differently from a failure.
+      if (resp.status === 404) {
+        throw new WorkspaceFileNotFoundError(path);
+      }
       if (!resp.ok) {
         throw new Error(
           `GitHub content fetch failed for ${path} (HTTP ${resp.status})`,

package/src/github/useGitHubTreeLister.ts

@@ -38,7 +38,8 @@ const TRUNCATION_MARKER: WorkspaceFileEntry = {
  * Creates a {@link WorkspaceFileLister} backed by the GitHub Trees API.
  *
  * Uses the existing client-side OAuth token (same one that powers
- * `GitHubRepoPicker`) to call `GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1`.
+ * `GitHubRepoPicker`) to call `GET /repos/{owner}/{repo}/git/trees/{ref}?recursive=1`,
+ * where the ref is the entry's `readRef` (write-back commit) or `gitBranch`.
  *
  * Returns `null` for:
  * - Non-git workspace entries
@@ -64,8 +65,11 @@ export function useGitHubTreeLister(
       const parsed = parseGitUrl(entry.gitUrl);
       if (!parsed) return null;
 
-      const branch = entry.gitBranch || "main";
-      const url = `${GITHUB_TREES_API}/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(branch)}?recursive=1`;
+      // readRef (the session's write-back commit SHA, when one exists) wins
+      // over the configured branch, so the tree includes agent-created files.
+      // The Trees API accepts a branch name or a commit SHA interchangeably.
+      const ref = entry.readRef || entry.gitBranch || "main";
+      const url = `${GITHUB_TREES_API}/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
 
       const resp = await fetch(url, {
         headers: { Authorization: `Bearer ${token}` },

package/src/index.ts

@@ -71,6 +71,7 @@ export {
   useWorkspaceContentSearch,
   useWorkspaceSources,
   MAX_WORKSPACE_FILE_READ_BYTES,
+  WorkspaceFileNotFoundError,
   WorkspaceEditor,
   WorkspaceFileSearch,
   WorkspaceContentSearch,
@@ -129,7 +130,9 @@ export {
   useSessionExecutions,
   useSessionConversation,
   useSessionArtifacts,
+  artifactKey,
   useSessionWriteBacks,
+  useWorkspaceReadRefs,
   useSessionFileChanges,
   useSessionUsage,
   useAgentRefFromSession,
@@ -154,6 +157,7 @@ export {
   PlanStreamingDocument,
   PLAN_DOCUMENT_ENTRY_ID,
   PLAN_DOCUMENT_PATH,
+  ARTIFACT_DOCUMENT_ENTRY_ID,
   SetupTab,
 } from "./session/index.js";
 export type {
@@ -231,6 +235,7 @@ export {
   deriveEffectiveVerdicts,
   changeForRowPath,
   fileReviewRowState,
+  fileReviewRowChange,
   foldFileReviewEventStream,
   displayFileChangeSets,
   toDisplayFileChange,
@@ -288,8 +293,12 @@ export {
   useApproval,
   FileReviewContext,
   useFileReviewRowState,
-  ArtifactCard,
+  useFileReviewRowChange,
+  ArtifactRow,
   ArtifactContentRenderer,
+  ArtifactContentBody,
+  ArtifactDocument,
+  useArtifactInspection,
   ArtifactPreviewContent,
   ArtifactPreviewModal,
   ArtifactsWidget,
@@ -381,8 +390,12 @@ export type {
   ApprovalContextValue,
   UseApprovalResult,
   FileReviewContextValue,
-  ArtifactCardProps,
+  ArtifactRowProps,
   ArtifactContentRendererProps,
+  ArtifactContentBodyProps,
+  ArtifactDocumentProps,
+  ArtifactInspection,
+  UseArtifactInspectionOptions,
   ArtifactRenderMode,
   ArtifactPreviewContentProps,
   ArtifactPreviewModalProps,