@stigmer/react 3.1.2 → 3.1.4

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/useArtifactCopy.ts

@@ -0,0 +1,109 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, 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.js";
+import { toError } from "../internal/toError.js";
+
+/** How long the transient `copied` flag stays true after a successful copy. */
+const COPIED_FEEDBACK_MS = 2000;
+
+/** Return value of {@link useArtifactCopy}. */
+export interface UseArtifactCopyReturn {
+  /**
+   * Fetch the artifact's text at click time and write it to the clipboard.
+   * No-op when the execution id is unknown or a copy is already in flight.
+   * Resolves once the copy has been attempted.
+   *
+   * @param storageKey - Storage key of the artifact to copy.
+   */
+  readonly copy: (storageKey: string) => Promise<void>;
+
+  /** `true` while the content is being fetched / written to the clipboard. */
+  readonly isCopying: boolean;
+
+  /**
+   * `true` for a brief window after a successful copy (drives "Copied"
+   * affordance feedback), then resets automatically.
+   */
+  readonly copied: boolean;
+
+  /** Error from the last failed copy attempt, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that copies an execution artifact's text to the clipboard on
+ * demand.
+ *
+ * The imperative sibling of {@link useArtifactDownload}: it fetches content at
+ * click time via `getArtifactContent` (CORS-safe, through the Stigmer API)
+ * rather than requiring the caller to have loaded it. This suits content-free
+ * surfaces — a plan card that detects the artifact by convention and never
+ * fetches until the user acts — where a mount-time {@link useArtifactContent}
+ * would be wasteful.
+ *
+ * Returns an imperative `copy(storageKey)` action plus a transient `copied`
+ * flag for feedback, mirroring the modal's copy affordance so every surface
+ * shares one implementation.
+ *
+ * @param executionId - Execution that produced the artifacts, or `null` to
+ *   disable (the action becomes a no-op).
+ *
+ * @example
+ * ```tsx
+ * const { copy, isCopying, copied } = useArtifactCopy(executionId);
+ * <button onClick={() => copy(artifact.storageKey)} disabled={isCopying}>
+ *   {copied ? "Copied" : "Copy"}
+ * </button>
+ * ```
+ *
+ * @see useArtifactDownload — imperative save-to-disk counterpart
+ * @see useArtifactContent — declarative content reader (preview rendering)
+ */
+export function useArtifactCopy(
+  executionId: string | null,
+): UseArtifactCopyReturn {
+  const stigmer = useStigmer();
+  const [isCopying, setIsCopying] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Clear the pending "copied" timer on unmount so a resolved copy never sets
+  // state on an unmounted component.
+  const copiedTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    return () => {
+      if (copiedTimer.current !== null) clearTimeout(copiedTimer.current);
+    };
+  }, []);
+
+  const copy = useCallback(
+    async (storageKey: string) => {
+      if (!executionId || !storageKey || isCopying) return;
+      setIsCopying(true);
+      setError(null);
+      try {
+        const result = await stigmer.agentExecution.getArtifactContent(
+          create(GetArtifactContentRequestSchema, { executionId, storageKey }),
+        );
+        const text = new TextDecoder().decode(result.content);
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        if (copiedTimer.current !== null) clearTimeout(copiedTimer.current);
+        copiedTimer.current = setTimeout(() => setCopied(false), COPIED_FEEDBACK_MS);
+      } catch (err) {
+        setError(toError(err));
+      } finally {
+        setIsCopying(false);
+      }
+    },
+    [executionId, stigmer, isCopying],
+  );
+
+  return useMemo(
+    () => ({ copy, isCopying, copied, error }),
+    [copy, isCopying, copied, error],
+  );
+}

package/src/execution/useArtifactDownload.ts

@@ -65,7 +65,16 @@ export function useArtifactDownload(
       setError(null);
       try {
         const result = await stigmer.agentExecution.getArtifactDownloadUrl(
-          create(GetArtifactDownloadUrlRequestSchema, { executionId, storageKey }),
+          create(GetArtifactDownloadUrlRequestSchema, {
+            executionId,
+            storageKey,
+            // This is a save-to-disk action, so mint a URL that forces a
+            // browser download (Content-Disposition: attachment). Browsers
+            // ignore the anchor's `download` attribute cross-origin, so the
+            // disposition must ride on the URL itself. Contrast
+            // useArtifactDownloadUrl, which stays inline for `<img src>`.
+            asAttachment: true,
+          }),
         );
         if (result.downloadUrl) {
           triggerBrowserDownload(result.downloadUrl, fileName);
@@ -86,10 +95,13 @@ export function useArtifactDownload(
 }
 
 /**
- * Trigger a browser download for a URL via a transient anchor click. The
- * `download` hint is best-effort: browsers ignore it for cross-origin URLs
- * (e.g. R2), in which case the navigation still serves the file. Falls back to
- * a new tab in non-DOM environments.
+ * Trigger a browser download for a URL via a transient anchor click.
+ *
+ * The URL minted for this flow carries `Content-Disposition: attachment`
+ * (requested via `asAttachment`), so the browser saves the file even
+ * cross-origin — where it would ignore the anchor's `download` attribute. The
+ * `download` hint is still set as a same-origin nicety. Falls back to a new tab
+ * in non-DOM environments.
  */
 function triggerBrowserDownload(url: string, fileName?: string): void {
   if (typeof document === "undefined") {

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

@@ -55,11 +55,13 @@ export interface CreateAgentExecutionInput {
    */
   readonly interactionMode?: "agent" | "plan";
   /**
-   * Marks this execution as a "Build from plan" turn: the user approved a
+   * Marks this execution as a Build-from-plan turn: the user approved a
    * plan from a prior Plan-mode execution and asked the agent to implement
    * it. The runner injects the implement-plan directive (pointing at the
-   * attached approved plan when present); the thread renders the turn as a
-   * compact chip instead of the raw message text.
+   * attached approved plan when present); the thread hides the turn's
+   * machine-written message entirely — the plan card above it is the
+   * visible cause. Surfaces without that treatment (the CLI, history)
+   * show the message text as-is.
    *
    * Maps to `ExecutionConfig.build_from_plan` in the proto.
    */
@@ -91,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}. */
@@ -197,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 {
@@ -283,12 +285,16 @@ export {
   ApprovalCardBody,
   FileReviewCard,
   FileReviewDock,
+  FileChangeProgressBar,
   ApprovalContext,
   useApproval,
   FileReviewContext,
   useFileReviewRowState,
-  ArtifactCard,
+  ArtifactRow,
   ArtifactContentRenderer,
+  ArtifactContentBody,
+  ArtifactDocument,
+  useArtifactInspection,
   ArtifactPreviewContent,
   ArtifactPreviewModal,
   ArtifactsWidget,
@@ -307,6 +313,7 @@ export {
   useArtifactContent,
   useArtifactDownloadUrl,
   useArtifactDownload,
+  useArtifactCopy,
   useToolOutputContent,
   useFileChangeContent,
   execIdFromStorageKey,
@@ -375,11 +382,16 @@ export type {
   ApprovalCardBodyProps,
   FileReviewCardProps,
   FileReviewDockProps,
+  FileChangeProgressBarProps,
   ApprovalContextValue,
   UseApprovalResult,
   FileReviewContextValue,
-  ArtifactCardProps,
+  ArtifactRowProps,
   ArtifactContentRendererProps,
+  ArtifactContentBodyProps,
+  ArtifactDocumentProps,
+  ArtifactInspection,
+  UseArtifactInspectionOptions,
   ArtifactRenderMode,
   ArtifactPreviewContentProps,
   ArtifactPreviewModalProps,
@@ -397,6 +409,7 @@ export type {
   UseArtifactDownloadUrlReturn,
   UseArtifactDownloadUrlOptions,
   UseArtifactDownloadReturn,
+  UseArtifactCopyReturn,
   UseToolOutputContentReturn,
   ToolOutputRefLike,
   UseFileChangeContentReturn,
@@ -980,10 +993,12 @@ export {
   detectSkillPackage,
   useDetectSkillPackage,
   isPlanArtifact,
+  isPlanArtifactName,
   findPlanArtifact,
   findLatestSessionPlan,
   findStreamingPlan,
   PLAN_ARTIFACT_NAME,
+  PLAN_ARTIFACT_SUFFIX,
   parseResourceYaml,
   serializeAgentYaml,
   serializeMcpServerYaml,