@stigmer/react 3.0.8-dev.20260613051837 → 3.0.8-dev.20260613072749

package/src/execution/MessageEntry.tsx

@@ -14,6 +14,13 @@ export interface MessageEntryProps {
   readonly message: AgentMessage;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
+  /**
+   * When provided on a `MESSAGE_HUMAN` entry, a hover-revealed "Edit" button
+   * appears on the bubble. Clicking it invokes this callback — the session
+   * chat uses it to stop the in-flight turn and pre-fill the composer with
+   * this message for editing. Ignored for non-human messages.
+   */
+  readonly onEdit?: () => void;
 }
 
 /**
@@ -43,6 +50,7 @@ export interface MessageEntryProps {
 export const MessageEntry = memo(function MessageEntry({
   message,
   className,
+  onEdit,
 }: MessageEntryProps) {
   useRenderTracer("MessageEntry", {
     messageType: message.type,
@@ -52,7 +60,13 @@ export const MessageEntry = memo(function MessageEntry({
 
   switch (message.type) {
     case MessageType.MESSAGE_HUMAN:
-      return <HumanMessage content={message.content} className={className} />;
+      return (
+        <HumanMessage
+          content={message.content}
+          className={className}
+          onEdit={onEdit}
+        />
+      );
     case MessageType.MESSAGE_AI:
       return (
         <AiMessage
@@ -79,21 +93,62 @@ export const MessageEntry = memo(function MessageEntry({
 function HumanMessage({
   content,
   className,
+  onEdit,
 }: {
   content: string;
   className?: string;
+  onEdit?: () => void;
 }) {
   return (
     <div
       role="article"
       aria-label="User message"
-      className={cn("ms-[20%] rounded-lg bg-muted-subtle px-4 py-3", className)}
+      className={cn(
+        "group relative ms-[20%] rounded-lg bg-muted-subtle px-4 py-3",
+        className,
+      )}
     >
       <p className="text-sm text-foreground whitespace-pre-wrap">{content}</p>
+      {onEdit && (
+        <button
+          type="button"
+          onClick={onEdit}
+          aria-label="Edit message"
+          title="Edit"
+          className={cn(
+            "absolute -top-2.5 -right-2.5 inline-flex h-7 w-7 items-center justify-center rounded-full",
+            "border border-border bg-card text-muted-foreground shadow-sm transition",
+            "hover:text-foreground hover:bg-accent-hover",
+            "opacity-0 group-hover:opacity-100 focus-visible:opacity-100",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        >
+          <EditIcon />
+        </button>
+      )}
     </div>
   );
 }
 
+function EditIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M12 20h9" />
+      <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4Z" />
+    </svg>
+  );
+}
+
 function AiMessage({
   content,
   isStreaming,

package/src/execution/MessageThread.tsx

@@ -74,6 +74,17 @@ export interface MessageThreadProps {
    * "Retry" control when {@link pendingMessageFailed} is `true`.
    */
   readonly onRetrySend?: () => void;
+  /**
+   * When provided, the in-flight human turn (the active execution's prompt)
+   * shows a hover "Edit" affordance. Clicking it invokes this callback with
+   * the message text — the session chat stops the running execution and
+   * pre-fills the composer for an edit-and-resubmit.
+   *
+   * Provide this only while the active execution is stoppable; the SDK marks
+   * exactly the active-stream human turn editable. When omitted, no edit
+   * control is shown (backward compatible).
+   */
+  readonly onEditMessage?: (text: string) => void;
   /**
    * Retry handler for a terminal-failed execution that exposed a server
    * error reason. Receives the originating message; the consumer typically
@@ -199,7 +210,7 @@ export interface MessageThreadProps {
  * part of the public API.
  */
 export type ThreadItem =
-  | { readonly kind: "message"; readonly message: AgentMessage; readonly key: string; readonly isPending?: boolean; readonly isFailed?: boolean }
+  | { readonly kind: "message"; readonly message: AgentMessage; readonly key: string; readonly isPending?: boolean; readonly isFailed?: boolean; readonly isEditable?: boolean }
   | { readonly kind: "tool-group"; readonly toolCalls: readonly ToolCall[]; readonly subAgentExecutions: readonly SubAgentExecution[]; readonly key: string }
   | { readonly kind: "sub-agent"; readonly subAgentExecution: SubAgentExecution; readonly key: string }
   | { readonly kind: "phase-badge"; readonly phase: ExecutionPhase; readonly key: string }
@@ -239,6 +250,7 @@ export function buildThreadItems(
   workspaceEntries: readonly WorkspaceEntry[] | undefined,
   summarizationEvents?: readonly SummarizationEventView[],
   pendingMessageFailed = false,
+  editableActiveTurn = false,
 ): ThreadItem[] {
   const items: ThreadItem[] = [];
   const allExecutions = activeStreamExecution
@@ -297,6 +309,9 @@ export function buildThreadItems(
         kind: "message",
         message: syntheticHumanMsg,
         key: bridgePending ? "pending-user-turn" : `${execId}-spec`,
+        // The active execution's prompt is the one a user can edit-and-resubmit
+        // (stop + rephrase). Only mark it when the consumer enabled editing.
+        isEditable: isActiveStreamExec && editableActiveTurn,
       });
     }
 
@@ -510,6 +525,7 @@ export function MessageThread({
   pendingMessageFailed = false,
   onRetrySend,
   onRetryExecution,
+  onEditMessage,
   className,
   formatToolCallSummary,
   onApprovalSubmit,
@@ -527,9 +543,10 @@ export function MessageThread({
   useRenderTracer("MessageThread", { executions, activeStreamExecution });
 
   const includeApprovals = onApprovalSubmit != null;
+  const editableActiveTurn = onEditMessage != null;
   const items = useMemo(
-    () => buildThreadItems(executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed),
-    [executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed],
+    () => buildThreadItems(executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed, editableActiveTurn),
+    [executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed, editableActiveTurn],
   );
 
   useKeyStability(items);
@@ -564,6 +581,7 @@ export function MessageThread({
             centerContent={centerContent}
             onRetrySend={onRetrySend}
             onRetryExecution={onRetryExecution}
+            onEditMessage={onEditMessage}
           />
         </Suspense>
       </div>
@@ -585,6 +603,7 @@ export function MessageThread({
       planActionsDisabled={planActionsDisabled}
       onRetrySend={onRetrySend}
       onRetryExecution={onRetryExecution}
+      onEditMessage={onEditMessage}
     />
   );
 }
@@ -611,6 +630,7 @@ interface NonVirtualizedThreadProps {
   readonly planActionsDisabled?: boolean;
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
+  readonly onEditMessage?: (text: string) => void;
 }
 
 function NonVirtualizedThread({
@@ -627,6 +647,7 @@ function NonVirtualizedThread({
   planActionsDisabled,
   onRetrySend,
   onRetryExecution,
+  onEditMessage,
 }: NonVirtualizedThreadProps) {
   const { scrollRef, sentinelRef, contentRef, isFollowing, jumpToLatest } =
     useAutoScroll();
@@ -664,6 +685,7 @@ function NonVirtualizedThread({
                   planActionsDisabled={planActionsDisabled}
                   onRetrySend={onRetrySend}
                   onRetryExecution={onRetryExecution}
+                  onEditMessage={onEditMessage}
                 />
               </ThreadItemWrapper>
             ))}
@@ -702,6 +724,7 @@ export interface ThreadItemRendererProps {
   readonly planActionsDisabled?: boolean;
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
+  readonly onEditMessage?: (text: string) => void;
 }
 
 /**
@@ -725,6 +748,7 @@ export function ThreadItemRenderer({
   planActionsDisabled,
   onRetrySend,
   onRetryExecution,
+  onEditMessage,
 }: ThreadItemRendererProps) {
   switch (item.kind) {
     case "message":
@@ -737,6 +761,11 @@ export function ThreadItemRenderer({
         <MessageEntry
           message={item.message}
           className={item.isPending ? "opacity-70" : undefined}
+          onEdit={
+            item.isEditable && onEditMessage
+              ? () => onEditMessage(item.message.content)
+              : undefined
+          }
         />
       );
     case "tool-group":

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

@@ -310,6 +310,72 @@ describe("MessageThread", () => {
     expect(onRetrySend).toHaveBeenCalledOnce();
   });
 
+  it("shows an Edit affordance on the in-flight human turn and routes onEditMessage", () => {
+    const active = makeExecution({
+      id: "exec-active",
+      specMessage: "fix the bug",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      aiContent: "working on it",
+    });
+    const onEditMessage = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={active}
+        onEditMessage={onEditMessage}
+      />,
+    );
+
+    const editBtn = screen.getByRole("button", { name: "Edit message" });
+    fireEvent.click(editBtn);
+    expect(onEditMessage).toHaveBeenCalledWith("fix the bug");
+  });
+
+  it("shows no Edit affordance when onEditMessage is omitted", () => {
+    const active = makeExecution({
+      id: "exec-active",
+      specMessage: "fix the bug",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    });
+
+    render(
+      <MessageThread executions={[]} activeStreamExecution={active} />,
+    );
+
+    expect(
+      screen.queryByRole("button", { name: "Edit message" }),
+    ).toBeNull();
+  });
+
+  it("marks only the active-stream human turn editable, not completed turns", () => {
+    const completed = makeExecution({
+      id: "exec-done",
+      specMessage: "old turn",
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+    });
+    const active = makeExecution({
+      id: "exec-active",
+      specMessage: "new turn",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    });
+    const onEditMessage = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[completed]}
+        activeStreamExecution={active}
+        onEditMessage={onEditMessage}
+      />,
+    );
+
+    const editBtns = screen.getAllByRole("button", { name: "Edit message" });
+    expect(editBtns).toHaveLength(1);
+
+    fireEvent.click(editBtns[0]);
+    expect(onEditMessage).toHaveBeenCalledWith("new turn");
+  });
+
   it("renders plan-completion card when last execution is completed Plan mode", () => {
     const exec = makeExecution({
       id: "exec-plan",

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

@@ -0,0 +1,299 @@
+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 { StigmerContext } from "../../context";
+import { useAgentExecutionActions } from "../useAgentExecutionActions";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeExecution(id = "aex-001", phase = 2 /* IN_PROGRESS */) {
+  return {
+    metadata: { id, name: "test-execution", org: "org-1" },
+    status: { phase },
+  } as any;
+}
+
+const mockCancel = vi.fn();
+const mockTerminate = vi.fn();
+const mockPause = vi.fn();
+const mockResume = vi.fn();
+
+function makeMockClient(): Stigmer {
+  return {
+    agentExecution: {
+      cancel: mockCancel,
+      terminate: mockTerminate,
+      pause: mockPause,
+      resume: mockResume,
+    },
+  } 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();
+});
+
+// ---------------------------------------------------------------------------
+// Lifecycle actions (cancel, terminate, pause, resume)
+// ---------------------------------------------------------------------------
+
+describe("useAgentExecutionActions", () => {
+  it("cancel returns updated execution on success", async () => {
+    const execution = makeExecution("aex-001", 5 /* CANCELLED */);
+    mockCancel.mockResolvedValueOnce(execution);
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    expect(result.current.isSubmitting).toBe(false);
+    expect(result.current.error).toBeNull();
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.cancel("No longer needed");
+    });
+
+    expect(returned).toBe(execution);
+    expect(result.current.isSubmitting).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(mockCancel).toHaveBeenCalledTimes(1);
+    expect(mockCancel.mock.calls[0][0]).toMatchObject({
+      id: "aex-001",
+      reason: "No longer needed",
+    });
+  });
+
+  it("terminate returns updated execution on success", async () => {
+    const execution = makeExecution("aex-001", 6 /* TERMINATED */);
+    mockTerminate.mockResolvedValueOnce(execution);
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.terminate("Force stop");
+    });
+
+    expect(returned).toBe(execution);
+    expect(mockTerminate).toHaveBeenCalledTimes(1);
+  });
+
+  it("sets error and returns null on failure", async () => {
+    mockCancel.mockRejectedValueOnce(new Error("Temporal not found"));
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.cancel();
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error!.message).toBe("Temporal not found");
+    expect(result.current.isSubmitting).toBe(false);
+  });
+
+  it("clearError resets error to null", async () => {
+    mockPause.mockRejectedValueOnce(new Error("oops"));
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.pause();
+    });
+    expect(result.current.error).not.toBeNull();
+
+    act(() => result.current.clearError());
+    expect(result.current.error).toBeNull();
+  });
+
+  it("error is cleared on next action attempt", async () => {
+    mockCancel
+      .mockRejectedValueOnce(new Error("first attempt failed"))
+      .mockResolvedValueOnce(makeExecution());
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.cancel();
+    });
+    expect(result.current.error!.message).toBe("first attempt failed");
+
+    await act(async () => {
+      await result.current.cancel();
+    });
+    expect(result.current.error).toBeNull();
+  });
+
+  it("null executionId returns null without calling SDK", async () => {
+    const { result } = renderHook(
+      () => useAgentExecutionActions(null),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.cancel();
+    });
+
+    expect(returned).toBeNull();
+    expect(mockCancel).not.toHaveBeenCalled();
+    expect(result.current.isSubmitting).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("resume sends only the id", async () => {
+    mockResume.mockResolvedValueOnce(makeExecution("aex-001", 2));
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.resume();
+    });
+
+    expect(mockResume).toHaveBeenCalledTimes(1);
+    expect(mockResume.mock.calls[0][0]).toMatchObject({ id: "aex-001" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// onSuccess callback
+// ---------------------------------------------------------------------------
+
+describe("onSuccess callback", () => {
+  it("fires after a successful lifecycle action", async () => {
+    const execution = makeExecution("aex-001", 5);
+    mockCancel.mockResolvedValueOnce(execution);
+    const onSuccess = vi.fn();
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001", { onSuccess }),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.cancel();
+    });
+
+    expect(onSuccess).toHaveBeenCalledTimes(1);
+    expect(onSuccess).toHaveBeenCalledWith(execution);
+  });
+
+  it("does not fire on failure", async () => {
+    mockCancel.mockRejectedValueOnce(new Error("fail"));
+    const onSuccess = vi.fn();
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001", { onSuccess }),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.cancel();
+    });
+
+    expect(onSuccess).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// stop() — progressive escalation cancel -> terminate
+// ---------------------------------------------------------------------------
+
+describe("stop escalation", () => {
+  it("first stop cancels, second stop terminates (same execution)", async () => {
+    mockCancel.mockResolvedValue(makeExecution("aex-001", 2));
+    mockTerminate.mockResolvedValue(makeExecution("aex-001", 6));
+
+    const { result } = renderHook(
+      () => useAgentExecutionActions("aex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.stop("Stop from chat");
+    });
+    expect(mockCancel).toHaveBeenCalledTimes(1);
+    expect(mockTerminate).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await result.current.stop("Stop from chat");
+    });
+    expect(mockCancel).toHaveBeenCalledTimes(1);
+    expect(mockTerminate).toHaveBeenCalledTimes(1);
+  });
+
+  it("escalation resets when the execution id changes", async () => {
+    mockCancel.mockResolvedValue(makeExecution());
+    mockTerminate.mockResolvedValue(makeExecution());
+
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string | null }) => useAgentExecutionActions(id),
+      {
+        wrapper: createWrapper(makeMockClient()),
+        initialProps: { id: "aex-001" as string | null },
+      },
+    );
+
+    await act(async () => {
+      await result.current.stop();
+    });
+    expect(mockCancel).toHaveBeenCalledTimes(1);
+
+    // A new in-flight execution — stop should cancel gracefully again,
+    // not inherit the prior execution's "escalate" state.
+    rerender({ id: "aex-002" });
+    await act(async () => {
+      await result.current.stop();
+    });
+    expect(mockCancel).toHaveBeenCalledTimes(2);
+    expect(mockTerminate).not.toHaveBeenCalled();
+  });
+
+  it("stop is a no-op for a null execution id", async () => {
+    const { result } = renderHook(
+      () => useAgentExecutionActions(null),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.stop();
+    });
+
+    expect(returned).toBeNull();
+    expect(mockCancel).not.toHaveBeenCalled();
+    expect(mockTerminate).not.toHaveBeenCalled();
+  });
+});

package/src/execution/index.ts

@@ -10,6 +10,12 @@ export { isTerminalPhase } from "./execution-phases";
 export { useExecutionStream } from "./useExecutionStream";
 export type { UseExecutionStreamReturn } from "./useExecutionStream";
 
+export { useAgentExecutionActions } from "./useAgentExecutionActions";
+export type {
+  UseAgentExecutionActionsOptions,
+  UseAgentExecutionActionsReturn,
+} from "./useAgentExecutionActions";
+
 export { UsageWidget, formatCost, formatTokenCount } from "./UsageWidget";
 export type { UsageWidgetProps } from "./UsageWidget";