@stigmer/react 3.0.8-dev.20260613041848 → 3.0.8-dev.20260613071809

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/__tests__/useExecutionStream.test.tsx

@@ -521,3 +521,98 @@ describe("useExecutionStream — auto-reconnect", () => {
     expect(subscribeFn).toHaveBeenCalledTimes(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Watchdog (#175) — silent connect timeout + slow-stall hint
+// ---------------------------------------------------------------------------
+
+describe("useExecutionStream — watchdog", () => {
+  const IN_PROGRESS = ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+  it("self-heals once then surfaces connectTimedOut on a silent connect", async () => {
+    // Every subscribe returns a stream that never delivers a snapshot.
+    const subscribeFn = vi.fn(
+      () => createControllableStream<AgentExecution>().generator,
+    );
+    const stigmer = createMockStigmer(
+      subscribeFn as unknown as Stigmer["agentExecution"]["subscribe"],
+    );
+
+    const { result } = renderHook(
+      () =>
+        useExecutionStream("exec-1", {
+          connectTimeoutMs: 20,
+          slowThresholdMs: 10_000,
+        }),
+      { wrapper: createWrapper(stigmer) },
+    );
+
+    // First timeout self-heals silently (no surfaced signal, a 2nd subscribe).
+    await waitFor(() => expect(subscribeFn).toHaveBeenCalledTimes(2));
+    // Second timeout surfaces the actionable signal — but never an error.
+    await waitFor(() => expect(result.current.connectTimedOut).toBe(true), {
+      timeout: 2000,
+    });
+    expect(result.current.error).toBeNull();
+  });
+
+  it("reconnect() clears connectTimedOut and re-subscribes", async () => {
+    const subscribeFn = vi.fn(
+      () => createControllableStream<AgentExecution>().generator,
+    );
+    const stigmer = createMockStigmer(
+      subscribeFn as unknown as Stigmer["agentExecution"]["subscribe"],
+    );
+
+    const { result } = renderHook(
+      () =>
+        useExecutionStream("exec-1", {
+          connectTimeoutMs: 20,
+          slowThresholdMs: 10_000,
+        }),
+      { wrapper: createWrapper(stigmer) },
+    );
+
+    await waitFor(() => expect(result.current.connectTimedOut).toBe(true), {
+      timeout: 2000,
+    });
+
+    const before = subscribeFn.mock.calls.length;
+    act(() => result.current.reconnect());
+
+    expect(result.current.connectTimedOut).toBe(false);
+    await waitFor(() =>
+      expect(subscribeFn.mock.calls.length).toBeGreaterThan(before),
+    );
+  });
+
+  it("flips isSlow on a silent live stream and clears it on the next snapshot", async () => {
+    const s = createControllableStream<AgentExecution>();
+    const subscribeFn = vi.fn(() => s.generator);
+    const stigmer = createMockStigmer(
+      subscribeFn as unknown as Stigmer["agentExecution"]["subscribe"],
+    );
+
+    const { result } = renderHook(
+      () =>
+        useExecutionStream("exec-1", {
+          connectTimeoutMs: 10_000,
+          slowThresholdMs: 20,
+        }),
+      { wrapper: createWrapper(stigmer) },
+    );
+
+    act(() => s.push(makeSnapshot(IN_PROGRESS)));
+    await waitFor(() => expect(result.current.isStreaming).toBe(true));
+
+    await waitFor(() => expect(result.current.isSlow).toBe(true), {
+      timeout: 2000,
+    });
+
+    // A terminal snapshot resolves the stall deterministically (no re-arm).
+    // The non-terminal "next snapshot clears + re-arms" path is covered without
+    // timing races in the StreamController unit test.
+    act(() => s.push(makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED)));
+    await waitFor(() => expect(result.current.isSlow).toBe(false));
+  });
+});

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";
 

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,
+  };
+}