@stigmer/react 3.1.1 → 3.1.3

package/src/execution/__tests__/message-entry.test.tsx

@@ -194,6 +194,23 @@ describe("MessageEntry — Human messages", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Build-from-plan turns — no special human-message treatment
+// ---------------------------------------------------------------------------
+
+describe("MessageEntry — Build-from-plan turns", () => {
+  it("renders any human message as the ordinary prompt bubble (the thread hides build turns before they reach MessageEntry)", () => {
+    // The retired chip treatment lived here; today buildThreadItems skips
+    // synthesizing the prompt item for a build turn entirely, so a human
+    // message that DOES reach MessageEntry is always ordinary prose.
+    const msg = makeMessage(MessageType.MESSAGE_HUMAN, "Build from plan");
+    const { container } = render(<MessageEntry message={msg} />);
+
+    expect(queryArticle(container, "User message")).not.toBeNull();
+    expect(queryArticle(container, "Build from plan")).toBeNull();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // System messages — unchanged
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useArtifactCopy } from "../useArtifactCopy";
+
+function wrapperFor(stigmer: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={stigmer}>{children}</StigmerContext.Provider>
+  );
+}
+
+function makeStigmer(getArtifactContent = vi.fn()) {
+  return { agentExecution: { getArtifactContent } } as unknown as Stigmer;
+}
+
+const writeText = vi.fn().mockResolvedValue(undefined);
+
+beforeEach(() => {
+  writeText.mockClear();
+  vi.stubGlobal("navigator", { clipboard: { writeText } });
+});
+
+describe("useArtifactCopy", () => {
+  it("fetches content at click time and writes decoded text to the clipboard", async () => {
+    const bytes = new TextEncoder().encode("# Plan\n\nsteps");
+    const fn = vi.fn().mockResolvedValue({ content: bytes });
+    const { result } = renderHook(() => useArtifactCopy("aex_1"), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+
+    expect(result.current.copied).toBe(false);
+    await act(async () => {
+      await result.current.copy("artifacts/aex_1/plan.md");
+    });
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    const req = fn.mock.calls[0][0];
+    expect(req.executionId).toBe("aex_1");
+    expect(req.storageKey).toBe("artifacts/aex_1/plan.md");
+    expect(writeText).toHaveBeenCalledWith("# Plan\n\nsteps");
+    expect(result.current.copied).toBe(true);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("resets the copied flag after the feedback window", async () => {
+    vi.useFakeTimers();
+    const bytes = new TextEncoder().encode("x");
+    const fn = vi.fn().mockResolvedValue({ content: bytes });
+    const { result } = renderHook(() => useArtifactCopy("aex_1"), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+
+    await act(async () => {
+      await result.current.copy("artifacts/aex_1/plan.md");
+    });
+    expect(result.current.copied).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(result.current.copied).toBe(false);
+    vi.useRealTimers();
+  });
+
+  it("is a no-op when the execution id is unknown", async () => {
+    const fn = vi.fn();
+    const { result } = renderHook(() => useArtifactCopy(null), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+    await act(async () => {
+      await result.current.copy("artifacts/x/plan.md");
+    });
+    expect(fn).not.toHaveBeenCalled();
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it("surfaces an error when the content RPC fails", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("boom"));
+    const { result } = renderHook(() => useArtifactCopy("aex_1"), {
+      wrapper: wrapperFor(makeStigmer(fn)),
+    });
+    await act(async () => {
+      await result.current.copy("artifacts/aex_1/plan.md");
+    });
+    await waitFor(() => expect(result.current.error?.message).toBe("boom"));
+    expect(result.current.copied).toBe(false);
+  });
+});

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

@@ -38,6 +38,8 @@ describe("useArtifactDownload", () => {
     const req = fn.mock.calls[0][0];
     expect(req.executionId).toBe("aex_1");
     expect(req.storageKey).toBe("artifacts/aex_1/file.bin");
+    // Save-to-disk actions force an attachment disposition on the minted URL.
+    expect(req.asAttachment).toBe(true);
     expect(result.current.isDownloading).toBe(false);
     expect(result.current.error).toBeNull();
   });

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

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StigmerContext } from "../../context";
+import { useCreateAgentExecution } from "../useCreateAgentExecution";
+
+const mockCreate = vi.fn();
+
+function makeMockClient(): Stigmer {
+  return {
+    agentExecution: { create: mockCreate },
+  } as unknown as Stigmer;
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>;
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockCreate.mockResolvedValue({ metadata: { id: "aex-1" } });
+});
+
+describe("useCreateAgentExecution — executionConfig mapping", () => {
+  it("maps buildFromPlan into executionConfig (the Build-from-plan turn)", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Build from plan",
+        interactionMode: "agent",
+        buildFromPlan: true,
+      });
+    });
+
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    expect(mockCreate.mock.calls[0][0].executionConfig).toMatchObject({
+      interactionMode: InteractionMode.AGENT,
+      buildFromPlan: true,
+    });
+  });
+
+  it("builds an executionConfig when buildFromPlan is the only config input", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Build from plan",
+        buildFromPlan: true,
+      });
+    });
+
+    expect(mockCreate.mock.calls[0][0].executionConfig).toMatchObject({
+      buildFromPlan: true,
+    });
+  });
+
+  it("omits executionConfig entirely for an ordinary message", 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].executionConfig).toBeUndefined();
+  });
+});

package/src/execution/index.ts

@@ -41,6 +41,12 @@ export type { PlanCompletionCardProps } from "./PlanCompletionCard.js";
 export { PlanArtifactCard } from "./PlanArtifactCard.js";
 export type { PlanArtifactCardProps } from "./PlanArtifactCard.js";
 
+export { PlanStreamingCard } from "./PlanStreamingCard.js";
+export type { PlanStreamingCardProps } from "./PlanStreamingCard.js";
+
+export { PlanDocumentMessage } from "./PlanDocumentMessage.js";
+export type { PlanDocumentMessageProps } from "./PlanDocumentMessage.js";
+
 export { useExecutionArtifacts } from "./useExecutionArtifacts.js";
 export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts.js";
 
@@ -56,6 +62,9 @@ export type {
 export { useArtifactDownload } from "./useArtifactDownload.js";
 export type { UseArtifactDownloadReturn } from "./useArtifactDownload.js";
 
+export { useArtifactCopy } from "./useArtifactCopy.js";
+export type { UseArtifactCopyReturn } from "./useArtifactCopy.js";
+
 export { useToolOutputContent } from "./useToolOutputContent.js";
 export type {
   UseToolOutputContentReturn,
@@ -160,7 +169,7 @@ export { MessageEntry } from "./MessageEntry.js";
 export type { MessageEntryProps } from "./MessageEntry.js";
 
 export { MessageThread } from "./MessageThread.js";
-export type { MessageThreadProps } from "./MessageThread.js";
+export type { MessageThreadProps, ThreadContentColumn } from "./MessageThread.js";
 
 export { ThreadSkeleton } from "./ThreadSkeleton.js";
 export type { ThreadSkeletonProps } from "./ThreadSkeleton.js";
@@ -224,6 +233,9 @@ export type { FileReviewCardProps } from "./FileReviewCard.js";
 export { FileReviewDock } from "./FileReviewDock.js";
 export type { FileReviewDockProps } from "./FileReviewDock.js";
 
+export { FileChangeProgressBar } from "./FileChangeProgressBar.js";
+export type { FileChangeProgressBarProps } from "./FileChangeProgressBar.js";
+
 export { ApprovalContext, useApproval } from "./ApprovalContext.js";
 export type { ApprovalContextValue, UseApprovalResult } from "./ApprovalContext.js";
 

package/src/execution/use-build-from-plan-hotkey.ts

@@ -3,7 +3,7 @@
 import { useCallback, type KeyboardEvent } from "react";
 
 /**
- * Card-scoped `Cmd/Ctrl+Enter` accelerator for the "Build from plan" action.
+ * Card-scoped `Cmd/Ctrl+Enter` accelerator for a plan card's "Build" action.
  *
  * Returns an `onKeyDown` handler for a plan card's root element. Because it is
  * attached to the card (not `window`), it fires only when the keystroke

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

@@ -54,6 +54,18 @@ export interface CreateAgentExecutionInput {
    * Maps to `ExecutionConfig.interaction_mode` in the proto.
    */
   readonly interactionMode?: "agent" | "plan";
+  /**
+   * 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 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.
+   */
+  readonly buildFromPlan?: boolean;
   /**
    * Auto-approve every tool call for this execution.
    *
@@ -158,7 +170,11 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
       setError(null);
 
       try {
-        const hasConfig = input.modelName || input.interactionMode || input.structuredOutputSchema;
+        const hasConfig =
+          input.modelName ||
+          input.interactionMode ||
+          input.structuredOutputSchema ||
+          input.buildFromPlan;
         const executionConfig = hasConfig
           ? {
               ...(input.modelName ? { modelName: input.modelName } : {}),
@@ -168,6 +184,7 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
               ...(input.structuredOutputSchema
                 ? { structuredOutputSchema: input.structuredOutputSchema }
                 : {}),
+              ...(input.buildFromPlan ? { buildFromPlan: true } : {}),
             }
           : undefined;
 

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

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import {
+  base64ToBytes,
+  detectBinary,
+  bytesToText,
+  normalizeGitHubContent,
+} from "../decodeGitHubContent";
+import { MAX_WORKSPACE_FILE_READ_BYTES } from "../../workspace/WorkspaceFileReader";
+
+function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+describe("base64ToBytes", () => {
+  it("decodes plain base64 to bytes", () => {
+    expect(bytesToText(base64ToBytes("SGVsbG8gV29ybGQh"))).toBe("Hello World!");
+  });
+
+  it("strips the newlines GitHub inserts every 60 chars", () => {
+    // GitHub's Contents API line-wraps its base64; atob would otherwise reject it.
+    const wrapped = "SGVsbG8g\nV29ybGQh\n";
+    expect(bytesToText(base64ToBytes(wrapped))).toBe("Hello World!");
+  });
+});
+
+describe("detectBinary", () => {
+  it("flags a buffer containing a NUL byte", () => {
+    expect(detectBinary(new Uint8Array([0x48, 0x00, 0x49]))).toBe(true);
+  });
+
+  it("treats NUL-free text as non-binary", () => {
+    expect(detectBinary(utf8("just some text"))).toBe(false);
+  });
+
+  it("only sniffs the head — a NUL past the sniff window is not detected", () => {
+    const bytes = new Uint8Array(9000).fill(0x61); // non-zero baseline
+    bytes[8500] = 0; // beyond the 8000-byte sniff window
+    expect(detectBinary(bytes)).toBe(false);
+  });
+});
+
+describe("bytesToText", () => {
+  it("decodes valid UTF-8", () => {
+    expect(bytesToText(utf8("héllo — 世界"))).toBe("héllo — 世界");
+  });
+
+  it("returns null for invalid UTF-8", () => {
+    // 0xFF is never a valid UTF-8 lead byte; the fatal decoder throws → null.
+    expect(bytesToText(new Uint8Array([0xff]))).toBeNull();
+  });
+});
+
+describe("normalizeGitHubContent", () => {
+  it("maps clean text to a utf-8 content record with the full size", () => {
+    const bytes = utf8("hello");
+    expect(normalizeGitHubContent(bytes, bytes.length)).toEqual({
+      text: "hello",
+      isBinary: false,
+      size: bytes.length,
+      encoding: "utf-8",
+    });
+  });
+
+  it("reports binary content with text null", () => {
+    const result = normalizeGitHubContent(new Uint8Array([0x00, 0x01, 0x02]), 3);
+    expect(result).toEqual({
+      text: null,
+      isBinary: true,
+      size: 3,
+      encoding: "base64",
+    });
+  });
+
+  it("marks undecodable (non-binary) bytes as unknown encoding", () => {
+    // 0xC0 is an invalid UTF-8 lead byte but not a NUL, so it is not "binary".
+    const result = normalizeGitHubContent(new Uint8Array([0xc0, 0x41]), 2);
+    expect(result).toEqual({
+      text: null,
+      isBinary: false,
+      size: 2,
+      encoding: "unknown",
+    });
+  });
+
+  it("truncates at the 1 MB cap and flags it, while size reports the full length", () => {
+    const total = MAX_WORKSPACE_FILE_READ_BYTES + 500;
+    const bytes = new Uint8Array(total).fill(0x61); // 'a'
+    const result = normalizeGitHubContent(bytes, total);
+
+    expect(result.truncated).toBe(true);
+    expect(result.size).toBe(total);
+    expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
+    expect(result.encoding).toBe("utf-8");
+  });
+
+  it("does not set truncated when exactly at the cap", () => {
+    const bytes = new Uint8Array(MAX_WORKSPACE_FILE_READ_BYTES).fill(0x61);
+    const result = normalizeGitHubContent(bytes, bytes.length);
+    expect(result.truncated).toBeUndefined();
+    expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
+  });
+});