@stigmer/react 3.1.3 → 3.1.4

package/src/execution/__tests__/useArtifactInspection.test.tsx

@@ -0,0 +1,151 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Stigmer } from "@stigmer/sdk";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StigmerContext } from "../../context";
+import { useArtifactInspection } from "../useArtifactInspection";
+
+function fileArtifact(name: string) {
+  return create(ExecutionArtifactSchema, {
+    name,
+    kind: ExecutionArtifactKind.FILE,
+    sizeBytes: 64n,
+    sandboxPath: `.stigmer/${name}`,
+    storageKey: `artifacts/aex_1/${name}`,
+    contentHash: "hash-1",
+  });
+}
+
+function dirArtifact(name: string) {
+  return create(ExecutionArtifactSchema, {
+    name,
+    kind: ExecutionArtifactKind.DIRECTORY,
+    sizeBytes: 512n,
+    sandboxPath: `.stigmer/${name}`,
+    storageKey: `artifacts/aex_1/${name}`,
+    entries: ["SKILL.md", "run.sh"],
+  });
+}
+
+function contentResult(text: string) {
+  return {
+    content: new TextEncoder().encode(text),
+    contentType: "text/plain",
+    truncated: false,
+  };
+}
+
+function wrapperFor(stigmer: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={stigmer}>{children}</StigmerContext.Provider>
+  );
+}
+
+const writeText = vi.fn().mockResolvedValue(undefined);
+
+beforeEach(() => {
+  writeText.mockClear();
+  vi.stubGlobal("navigator", { clipboard: { writeText } });
+});
+
+const AGENT_YAML = [
+  "apiVersion: agentic.stigmer.ai/v1",
+  "kind: Agent",
+  "metadata:",
+  "  name: my-agent",
+  "spec: {}",
+  "",
+].join("\n");
+
+describe("useArtifactInspection — content + copy", () => {
+  it("fetches text content and copies it to the clipboard on demand", async () => {
+    const getArtifactContent = vi.fn().mockResolvedValue(contentResult("hello world"));
+    const stigmer = { agentExecution: { getArtifactContent } } as unknown as Stigmer;
+
+    const { result } = renderHook(
+      () => useArtifactInspection(fileArtifact("notes.txt"), "aex_1", "acme"),
+      { wrapper: wrapperFor(stigmer) },
+    );
+
+    await waitFor(() => expect(result.current.content).toBe("hello world"));
+    expect(result.current.isDirectory).toBe(false);
+    expect(result.current.isDetected).toBe(false);
+    expect(result.current.ctaLabel).toBeNull();
+
+    act(() => {
+      result.current.copy();
+    });
+    expect(writeText).toHaveBeenCalledWith("hello world");
+    await waitFor(() => expect(result.current.copied).toBe(true));
+  });
+
+  it("does not fetch content for a directory artifact", () => {
+    const getArtifactContent = vi.fn().mockReturnValue(new Promise(() => {}));
+    const stigmer = { agentExecution: { getArtifactContent } } as unknown as Stigmer;
+
+    const { result } = renderHook(
+      () => useArtifactInspection(dirArtifact("skill-pack"), "aex_1", "acme"),
+      { wrapper: wrapperFor(stigmer) },
+    );
+
+    expect(result.current.isDirectory).toBe(true);
+    // Directory content is not fetched via the text-content RPC (skill
+    // detection uses its own entry-scoped fetch).
+    expect(
+      getArtifactContent.mock.calls.every(
+        (call) => call[0]?.entryPath !== undefined,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("useArtifactInspection — detection + apply", () => {
+  it("labels a detected Agent YAML and offers an Apply CTA", async () => {
+    const getArtifactContent = vi.fn().mockResolvedValue(contentResult(AGENT_YAML));
+    const stigmer = { agentExecution: { getArtifactContent } } as unknown as Stigmer;
+
+    const { result } = renderHook(
+      () => useArtifactInspection(fileArtifact("agent.yaml"), "aex_1", "acme"),
+      { wrapper: wrapperFor(stigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isDetected).toBe(true));
+    expect(result.current.detectionLabel).toBe("Agent detected");
+    expect(result.current.ctaLabel).toBe("Apply to acme");
+  });
+
+  it("applies a detected Agent and fires onApplied with the result", async () => {
+    const getArtifactContent = vi.fn().mockResolvedValue(contentResult(AGENT_YAML));
+    const apply = vi.fn().mockResolvedValue({
+      metadata: { name: "my-agent", org: "acme", slug: "my-agent" },
+    });
+    const stigmer = {
+      agentExecution: { getArtifactContent },
+      agent: { apply },
+    } as unknown as Stigmer;
+    const onApplied = vi.fn();
+
+    const { result } = renderHook(
+      () =>
+        useArtifactInspection(fileArtifact("agent.yaml"), "aex_1", "acme", {
+          onApplied,
+        }),
+      { wrapper: wrapperFor(stigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isDetected).toBe(true));
+
+    await act(async () => {
+      await result.current.apply();
+    });
+
+    expect(apply).toHaveBeenCalledTimes(1);
+    expect(apply.mock.calls[0][0].name).toBe("my-agent");
+    await waitFor(() => expect(result.current.applyResult?.kind).toBe("Agent"));
+    expect(onApplied).toHaveBeenCalledTimes(1);
+    expect(onApplied.mock.calls[0][0].name).toBe("my-agent");
+  });
+});

package/src/execution/__tests__/useCreateAgentExecution.test.tsx

@@ -83,3 +83,38 @@ describe("useCreateAgentExecution — executionConfig mapping", () => {
     expect(mockCreate.mock.calls[0][0].executionConfig).toBeUndefined();
   });
 });
+
+describe("useCreateAgentExecution — supersede link (edit-and-resubmit)", () => {
+  it("maps supersedesExecutionId into the create call", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "corrected message",
+        supersedesExecutionId: "aex-old",
+      });
+    });
+
+    expect(mockCreate.mock.calls[0][0].supersedesExecutionId).toBe("aex-old");
+  });
+
+  it("leaves supersedesExecutionId undefined for ordinary sends", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Hello",
+      });
+    });
+
+    expect(mockCreate.mock.calls[0][0].supersedesExecutionId).toBeUndefined();
+  });
+});

package/src/execution/index.ts

@@ -242,12 +242,24 @@ export type { ApprovalContextValue, UseApprovalResult } from "./ApprovalContext.
 export { FileReviewContext, useFileReviewRowState } 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/index.ts

@@ -129,6 +129,7 @@ export {
   useSessionExecutions,
   useSessionConversation,
   useSessionArtifacts,
+  artifactKey,
   useSessionWriteBacks,
   useSessionFileChanges,
   useSessionUsage,
@@ -154,6 +155,7 @@ export {
   PlanStreamingDocument,
   PLAN_DOCUMENT_ENTRY_ID,
   PLAN_DOCUMENT_PATH,
+  ARTIFACT_DOCUMENT_ENTRY_ID,
   SetupTab,
 } from "./session/index.js";
 export type {
@@ -288,8 +290,11 @@ export {
   useApproval,
   FileReviewContext,
   useFileReviewRowState,
-  ArtifactCard,
+  ArtifactRow,
   ArtifactContentRenderer,
+  ArtifactContentBody,
+  ArtifactDocument,
+  useArtifactInspection,
   ArtifactPreviewContent,
   ArtifactPreviewModal,
   ArtifactsWidget,
@@ -381,8 +386,12 @@ export type {
   ApprovalContextValue,
   UseApprovalResult,
   FileReviewContextValue,
-  ArtifactCardProps,
+  ArtifactRowProps,
   ArtifactContentRendererProps,
+  ArtifactContentBodyProps,
+  ArtifactDocumentProps,
+  ArtifactInspection,
+  UseArtifactInspectionOptions,
   ArtifactRenderMode,
   ArtifactPreviewContentProps,
   ArtifactPreviewModalProps,