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

package/src/execution/useAgentExecutionActions.ts

@@ -0,0 +1,205 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { create } from "@bufbuild/protobuf";
+import {
+  CancelAgentExecutionInputSchema,
+  TerminateAgentExecutionInputSchema,
+  PauseAgentExecutionInputSchema,
+  ResumeAgentExecutionInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Options for {@link useAgentExecutionActions}. */
+export interface UseAgentExecutionActionsOptions {
+  /**
+   * Called after any lifecycle action (cancel, terminate, pause, resume)
+   * succeeds. Receives the updated execution returned by the server.
+   * Useful for triggering a refetch so the UI reflects the new phase.
+   */
+  readonly onSuccess?: (execution: AgentExecution) => void;
+}
+
+/** Return value of {@link useAgentExecutionActions}. */
+export interface UseAgentExecutionActionsReturn {
+  /** Cancel a running execution gracefully (PENDING or IN_PROGRESS only). */
+  readonly cancel: (reason?: string) => Promise<AgentExecution | null>;
+  /** Terminate a running execution immediately (PENDING or IN_PROGRESS only). */
+  readonly terminate: (reason?: string) => Promise<AgentExecution | null>;
+  /** Pause a running execution (PENDING or IN_PROGRESS only). */
+  readonly pause: (reason?: string) => Promise<AgentExecution | null>;
+  /** Resume a paused execution. */
+  readonly resume: () => Promise<AgentExecution | null>;
+  /**
+   * Stop a running execution with progressive escalation.
+   *
+   * The first call gracefully {@link cancel}s — the agent gets a chance to
+   * checkpoint and clean up. If the user presses Stop again because the run
+   * is still winding down, this escalates to a forceful {@link terminate}.
+   * The escalation state is keyed to the execution id, so a fresh execution
+   * always starts from a graceful cancel.
+   *
+   * @param reason - Optional audit message recorded with the cancel/terminate.
+   */
+  readonly stop: (reason?: string) => Promise<AgentExecution | null>;
+  /** `true` while any action is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed action, or `null`. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that encapsulates agent execution lifecycle actions.
+ *
+ * The agent-execution analog of {@link useWorkflowExecutionActions}: each
+ * action calls the corresponding RPC and returns the updated execution, or
+ * `null` on failure (with `error` populated).
+ *
+ * Pass `null` for `executionId` to disable all actions (they become no-ops
+ * that return `null`).
+ *
+ * Headless by design — embedders can wire a custom Stop/Cancel control
+ * directly to this hook. The session chat uses it via
+ * {@link useSessionConversation}'s `stop` / `isStoppable`.
+ *
+ * @example
+ * ```tsx
+ * const actions = useAgentExecutionActions(executionId, {
+ *   onSuccess: () => refetch(),
+ * });
+ *
+ * // A single Stop button that escalates on repeat press.
+ * <button onClick={() => actions.stop()} disabled={actions.isSubmitting}>
+ *   Stop
+ * </button>
+ * ```
+ */
+export function useAgentExecutionActions(
+  executionId: string | null,
+  options?: UseAgentExecutionActionsOptions,
+): UseAgentExecutionActionsReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const executionIdRef = useRef(executionId);
+  executionIdRef.current = executionId;
+  const stigmerRef = useRef(stigmer);
+  stigmerRef.current = stigmer;
+  const onSuccessRef = useRef(options?.onSuccess);
+  onSuccessRef.current = options?.onSuccess;
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const wrap = useCallback(
+    async (
+      fn: () => Promise<AgentExecution>,
+    ): Promise<AgentExecution | null> => {
+      if (!executionIdRef.current) return null;
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        const result = await fn();
+        onSuccessRef.current?.(result);
+        return result;
+      } catch (err) {
+        setError(toError(err));
+        return null;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [],
+  );
+
+  const cancel = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.agentExecution.cancel(
+          create(CancelAgentExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const terminate = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.agentExecution.terminate(
+          create(TerminateAgentExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const pause = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.agentExecution.pause(
+          create(PauseAgentExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const resume = useCallback(
+    () =>
+      wrap(() =>
+        stigmerRef.current.agentExecution.resume(
+          create(ResumeAgentExecutionInputSchema, {
+            id: executionIdRef.current!,
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  // Escalation state: remembers whether a graceful cancel has already been
+  // issued for the current execution id. Keyed by id so a new execution
+  // always begins with cancel rather than inheriting a stale "escalate" flag.
+  const stopStateRef = useRef<{ id: string; cancelIssued: boolean } | null>(
+    null,
+  );
+
+  const stop = useCallback(
+    (reason?: string): Promise<AgentExecution | null> => {
+      const id = executionIdRef.current;
+      if (!id) return Promise.resolve(null);
+
+      if (stopStateRef.current?.id !== id) {
+        stopStateRef.current = { id, cancelIssued: false };
+      }
+
+      if (!stopStateRef.current.cancelIssued) {
+        stopStateRef.current.cancelIssued = true;
+        return cancel(reason);
+      }
+      return terminate(reason);
+    },
+    [cancel, terminate],
+  );
+
+  return {
+    cancel,
+    terminate,
+    pause,
+    resume,
+    stop,
+    isSubmitting,
+    error,
+    clearError,
+  };
+}

package/src/index.ts

@@ -180,6 +180,7 @@ export {
   isTerminalPhase,
   useCreateAgentExecution,
   useExecutionStream,
+  useAgentExecutionActions,
   useSubmitApproval,
   ExecutionPhaseBadge,
   InteractionModeBadge,
@@ -251,6 +252,8 @@ export type {
   CreateAgentExecutionResult,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
+  UseAgentExecutionActionsOptions,
+  UseAgentExecutionActionsReturn,
   UseSubmitApprovalReturn,
   ExecutionPhaseBadgeProps,
   InteractionModeBadgeProps,

package/src/internal/VirtualizedThread.tsx

@@ -43,6 +43,7 @@ export interface VirtualizedThreadProps {
   readonly centerContent?: boolean;
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
+  readonly onEditMessage?: (text: string) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -105,6 +106,7 @@ export function VirtualizedThread({
   centerContent,
   onRetrySend,
   onRetryExecution,
+  onEditMessage,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -138,8 +140,9 @@ export function VirtualizedThread({
       planActionsDisabled,
       onRetrySend,
       onRetryExecution,
+      onEditMessage,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution, onEditMessage],
   );
 
   return (

package/src/session/SessionViewer.tsx

@@ -288,7 +288,8 @@ function ConversationColumn({
   isEndUser,
 }: ConversationColumnProps) {
   const { conv } = flow;
-  const sendError = flow.submitError ?? conv.sendError ?? conv.approvalError;
+  const sendError =
+    flow.submitError ?? conv.sendError ?? conv.approvalError ?? conv.stopError;
 
   // Retry a terminal-failed execution by resending its originating message
   // through the full submit pipeline (agent override, runtime-env, workspace).
@@ -299,6 +300,26 @@ function ConversationColumn({
     [flow.handleSubmit],
   );
 
+  // Stop the in-flight turn (graceful cancel, escalating to terminate on a
+  // repeat press). Only wired while the active execution is stoppable.
+  const handleStop = useCallback(() => {
+    void conv.stop();
+  }, [conv.stop]);
+
+  // Edit-and-resubmit: stop the in-flight turn and pre-fill the composer with
+  // the original text. The append-only execution log can't be rewritten, so
+  // the user reviews the prefilled message and resubmits it as a NEW execution
+  // through the normal Send pipeline. The cancelled turn stays in history with
+  // its phase badge — an honest record rather than a silent edit.
+  const handleEditMessage = useCallback(
+    (text: string) => {
+      void conv.stop();
+      composerRef.current?.setMessage(text);
+      composerRef.current?.focus();
+    },
+    [conv.stop, composerRef],
+  );
+
   return (
     <div className="flex h-full min-w-0 flex-col">
       <MessageThread
@@ -310,6 +331,7 @@ function ConversationColumn({
         onRetryExecution={onRetryExecution}
         onApprovalSubmit={flow.submitApproval}
         submittingApprovalIds={conv.submittingApprovalIds}
+        onEditMessage={conv.isStoppable ? handleEditMessage : undefined}
         workspaceEntries={conv.workspaceEntries}
         sandboxWorkspaceRoot={flow.sandboxWorkspaceRoot}
         onBuildFromPlan={onBuildFromPlan}
@@ -339,6 +361,8 @@ function ConversationColumn({
           onSubmit={flow.handleSubmit}
           isSubmitting={conv.isSending}
           disabled={!conv.canSendFollowUp}
+          onStop={conv.isStoppable ? handleStop : undefined}
+          isStopping={conv.isStopping}
           org={org}
           harness={flow.harness}
           defaultModelId={modelId}

package/src/session/__tests__/useSessionConversation.test.tsx

@@ -81,6 +81,8 @@ interface MockMethods {
   executionCreate: ReturnType<typeof vi.fn>;
   subscribe: ReturnType<typeof vi.fn>;
   submitApproval: ReturnType<typeof vi.fn>;
+  cancel?: ReturnType<typeof vi.fn>;
+  terminate?: ReturnType<typeof vi.fn>;
 }
 
 function createMockStigmer(methods: MockMethods): Stigmer {
@@ -93,6 +95,8 @@ function createMockStigmer(methods: MockMethods): Stigmer {
       create: methods.executionCreate,
       subscribe: methods.subscribe,
       submitApproval: methods.submitApproval,
+      cancel: methods.cancel,
+      terminate: methods.terminate,
     },
   } as unknown as Stigmer;
 }
@@ -118,6 +122,8 @@ describe("useSessionConversation", () => {
       executionCreate: vi.fn(),
       subscribe: vi.fn().mockReturnValue(stream.generator),
       submitApproval: vi.fn().mockResolvedValue({}),
+      cancel: vi.fn().mockResolvedValue(makeExecution("e1", ExecutionPhase.EXECUTION_CANCELLED)),
+      terminate: vi.fn().mockResolvedValue(makeExecution("e1", ExecutionPhase.EXECUTION_TERMINATED)),
     };
     mockStigmer = createMockStigmer(methods);
   });
@@ -411,6 +417,92 @@ describe("useSessionConversation", () => {
       }),
     );
   });
+
+  it("isStoppable is false when no execution is active", async () => {
+    const completed = makeExecution("e1", ExecutionPhase.EXECUTION_COMPLETED);
+    methods.listBySession.mockResolvedValue({ entries: [completed] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isStoppable).toBe(false);
+  });
+
+  it("isStoppable becomes true once the active execution streams IN_PROGRESS", async () => {
+    const active = makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    methods.listBySession.mockResolvedValue({ entries: [active] });
+
+    const execStream = createControllableStream<AgentExecution>();
+    methods.subscribe.mockReturnValue(execStream.generator);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    act(() => {
+      execStream.push(makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+
+    await waitFor(() => expect(result.current.isStoppable).toBe(true));
+  });
+
+  it("stop() cancels the active execution, then escalates to terminate on repeat", async () => {
+    const active = makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    methods.listBySession.mockResolvedValue({ entries: [active] });
+
+    const execStream = createControllableStream<AgentExecution>();
+    methods.subscribe.mockReturnValue(execStream.generator);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    act(() => {
+      execStream.push(makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+    await waitFor(() => expect(result.current.isStoppable).toBe(true));
+
+    await act(async () => {
+      await result.current.stop("Stop from chat");
+    });
+    expect(methods.cancel).toHaveBeenCalledTimes(1);
+    expect(methods.cancel!.mock.calls[0][0]).toMatchObject({ id: "e1" });
+    expect(methods.terminate).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await result.current.stop("Stop from chat");
+    });
+    expect(methods.cancel).toHaveBeenCalledTimes(1);
+    expect(methods.terminate).toHaveBeenCalledTimes(1);
+  });
+
+  it("stop() is a no-op when nothing is stoppable", async () => {
+    const completed = makeExecution("e1", ExecutionPhase.EXECUTION_COMPLETED);
+    methods.listBySession.mockResolvedValue({ entries: [completed] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.stop();
+    });
+
+    expect(methods.cancel).not.toHaveBeenCalled();
+    expect(methods.terminate).not.toHaveBeenCalled();
+  });
 });
 
 describe("useSessionConversation — local runner worker lifecycle", () => {

package/src/session/useSessionConversation.ts

@@ -21,6 +21,7 @@ import { toError } from "../internal/toError";
 import { useConversationStoreRef } from "../internal/store";
 import { useCreateAgentExecution } from "../execution/useCreateAgentExecution";
 import { useExecutionStream } from "../execution/useExecutionStream";
+import { useAgentExecutionActions } from "../execution/useAgentExecutionActions";
 import { useSubmitApproval } from "../execution/useSubmitApproval";
 import { useSession } from "./useSession";
 import { useSessionExecutions } from "./useSessionExecutions";
@@ -200,6 +201,28 @@ export interface UseSessionConversationReturn {
   /** Reset `approvalError` to `null`. */
   readonly clearApprovalError: () => void;
 
+  /**
+   * `true` when the active execution can be stopped — i.e. it is in a phase
+   * the backend accepts a cancel/terminate from (`PENDING` or `IN_PROGRESS`).
+   *
+   * Distinct from "is something active": an execution paused at an approval
+   * gate (`WAITING_FOR_APPROVAL`) is active but **not** stoppable — the
+   * approval card (approve / skip / reject) is its control surface. Drive the
+   * composer's Stop affordance off this so it only appears when {@link stop}
+   * will actually succeed.
+   */
+  readonly isStoppable: boolean;
+  /**
+   * Stop the active execution, with progressive escalation: the first call
+   * gracefully cancels; a repeat call (because the run is still winding down)
+   * forcefully terminates. No-op when nothing is {@link isStoppable}.
+   */
+  readonly stop: (reason?: string) => Promise<void>;
+  /** `true` while a stop (cancel/terminate) request is in flight. */
+  readonly isStopping: boolean;
+  /** Error from the last stop attempt, or `null` when healthy. */
+  readonly stopError: Error | null;
+
   /** `true` while the session or execution list is loading. */
   readonly isLoading: boolean;
   /** Error from session or execution list loading, or `null` when healthy. */
@@ -431,6 +454,28 @@ export function useSessionConversation(
     return stream.phase;
   }, [activeExecutionId, stream.phase]);
 
+  // Stop is only valid in phases the backend cancels/terminates from
+  // (PENDING / IN_PROGRESS). Other non-terminal phases (e.g.
+  // WAITING_FOR_APPROVAL) are handled by their own control surface.
+  const isStoppable =
+    activePhase === ExecutionPhase.EXECUTION_PENDING ||
+    activePhase === ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+  const stopActions = useAgentExecutionActions(activeExecutionId, {
+    // The cancel/terminate also broadcasts the new phase over the stream, but
+    // refetch is the belt-and-suspenders that clears the active id even if the
+    // stream has already ended — mirrors the workflow viewer's onSuccess.
+    onSuccess: refetch,
+  });
+
+  const stop = useCallback(
+    async (reason?: string): Promise<void> => {
+      if (!isStoppable) return;
+      await stopActions.stop(reason);
+    },
+    [isStoppable, stopActions.stop],
+  );
+
   const canSendFollowUp = !isCreating && activeExecutionId === null;
 
   const workspaceEntries = useMemo<readonly ProtoWorkspaceEntry[]>(
@@ -563,6 +608,11 @@ export function useSessionConversation(
     approvalError,
     clearApprovalError,
 
+    isStoppable,
+    stop,
+    isStopping: stopActions.isSubmitting,
+    stopError: stopActions.error,
+
     isLoading,
     loadError,