@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/execution/SubAgentSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { memo, useMemo, useState } from "react";
+import { memo, useContext, useMemo } from "react";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
 import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
@@ -9,10 +9,13 @@ import {
   SubAgentStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { useRenderTracer } from "../internal/dev";
+import { useAutoDisclosure } from "../internal/useAutoDisclosure";
+import { useElapsedSince, formatElapsed } from "../internal/useElapsedSince";
 import { cn } from "@stigmer/theme";
 import { formatDuration } from "./ToolCallDetail";
 import { MessageEntry } from "./MessageEntry";
 import { ToolCallGroup } from "./ToolCallGroup";
+import { ApprovalContext } from "./ApprovalContext";
 import { isInternalTool } from "./tool-categories";
 import { useThreadSelection } from "./useThreadSelection";
 import {
@@ -144,17 +147,33 @@ function CollapsibleCard({
   selection,
   className,
 }: CollapsibleCardProps) {
-  const [expanded, setExpanded] = useState(false);
-
-  const handleToggle = () => {
-    setExpanded((v) => !v);
-  };
-
   const hasTodos =
     sub.todos != null && Object.keys(sub.todos).length > 0;
   const isRunning = sub.status === SubAgentStatus.SUB_AGENT_IN_PROGRESS;
   const isCompleted = sub.status === SubAgentStatus.SUB_AGENT_COMPLETED;
 
+  // A gate raised inside this sub-agent must be reachable: a delegated tool
+  // can stop the run just like a top-level one. We detect one of this
+  // sub-agent's tool calls awaiting approval and auto-open so its inline
+  // approval (rendered by the nested ToolCallItem) is visible without a click.
+  const { approvalsByToolCallId } = useContext(ApprovalContext);
+  const hasPendingApprovalInside = useMemo(() => {
+    if (approvalsByToolCallId.size === 0) return false;
+    for (const msg of sub.messages) {
+      if (msg.type !== MessageType.MESSAGE_AI) continue;
+      for (const tc of msg.toolCalls) {
+        if (tc.id && approvalsByToolCallId.has(tc.id)) return true;
+      }
+    }
+    return false;
+  }, [sub.messages, approvalsByToolCallId]);
+
+  // Open while running or while a nested gate waits; settle closed (keeping the
+  // todo/summary preview) when done — unless the user takes manual control.
+  const [expanded, handleToggle] = useAutoDisclosure(
+    isRunning || hasPendingApprovalInside,
+  );
+
   const activeTodo = useMemo(() => findActiveTodo(sub.todos), [sub.todos]);
   const completionLabel = useMemo(
     () => (isCompleted && hasTodos ? todoCompletionSummary(sub.todos) : null),
@@ -207,10 +226,14 @@ function CollapsibleCard({
         >
           {statusInfo.label}
         </span>
-        {duration && (
-          <span className="shrink-0 tabular-nums text-muted-foreground">
-            {duration}
-          </span>
+        {isRunning ? (
+          <RunningDuration startedAt={sub.startedAt} />
+        ) : (
+          duration && (
+            <span className="shrink-0 tabular-nums text-muted-foreground">
+              {duration}
+            </span>
+          )
         )}
         {selection && (
           <button
@@ -271,6 +294,30 @@ function CollapsibleCard({
   );
 }
 
+/**
+ * Ticking elapsed time for an IN_PROGRESS sub-agent's header, where the
+ * static duration (which needs `completedAt`) is still null.
+ *
+ * This is the honest live affordance for a running sub-agent: the Cursor
+ * SDK returns sub-agent internals only as a blob when the task tool
+ * completes (verified against SDK 1.0.13 and 1.0.22 — zero events reach the
+ * parent stream while the sub-agent runs), so there are no nested tool calls
+ * to stream here. A counter that visibly advances tells the user work is
+ * progressing without fabricating intermediate state. The native harness
+ * streams nested messages as they happen; this counter simply accompanies
+ * them.
+ */
+function RunningDuration({ startedAt }: { readonly startedAt: string }) {
+  const elapsed = useElapsedSince(startedAt);
+  if (elapsed === null) return null;
+
+  return (
+    <span className="shrink-0 tabular-nums text-muted-foreground">
+      {formatElapsed(elapsed)}
+    </span>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Flat content — no toggle (used inside ToolCallItem detail panel)
 // ---------------------------------------------------------------------------

package/src/execution/TerminalSession.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+// One rendered terminal session: the `$ command` prompt line followed by its
+// output, as a single block. Rendered on the same `bg-muted-subtle` surface as
+// every other code/output block (CollapsibleCode, search, list) — not a
+// bespoke dark box — so it tracks the host theme, preset, and color mode.
+
+import { cn } from "@stigmer/theme";
+import { CollapsiblePre } from "./tool-rendering-primitives";
+import { useSandboxNormalize } from "./SandboxContext";
+
+/** Props for {@link TerminalSession}. */
+export interface TerminalSessionProps {
+  /**
+   * The command that was run, shown as the `$ <command>` prompt line. Omit for
+   * a pure-output render; the pre-execution approval gate passes only this
+   * (no output exists yet).
+   */
+  readonly command?: string;
+  /** Standard output. */
+  readonly stdout?: string;
+  /** Standard error, rendered in the destructive color. */
+  readonly stderr?: string;
+  /** Process exit code. A non-zero code renders a trailing `exit N` badge. */
+  readonly exitCode?: number;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Renders a shell tool call as a single, cohesive terminal session — the
+ * command prompt line immediately followed by its output — instead of a
+ * separate command box and output box.
+ *
+ * Used by {@link ResultView} (full session) and the approval gate's
+ * {@link ToolArgsView} (command-only, pre-execution). Importable on its own by
+ * platform builders composing custom tool UIs.
+ *
+ * @example
+ * ```tsx
+ * <TerminalSession command="ls -la" stdout="total 8\n..." exitCode={0} />
+ * <TerminalSession command="npm test" /> // gate: command only
+ * ```
+ */
+export function TerminalSession({
+  command,
+  stdout,
+  stderr,
+  exitCode,
+  className,
+}: TerminalSessionProps) {
+  const normalize = useSandboxNormalize();
+  const failed = exitCode !== undefined && exitCode !== 0;
+
+  return (
+    <div
+      data-cursor-target="terminal-session"
+      className={cn(
+        "space-y-1 rounded-md border border-border bg-muted-subtle p-2.5 font-mono text-xs",
+        className,
+      )}
+    >
+      {command && (
+        // A plain <pre> (not CollapsiblePre): the command is the user's intent
+        // and renders in full — even a multi-line heredoc — without a second
+        // truncation toggle competing with stdout's.
+        <pre className="whitespace-pre-wrap break-words text-foreground">
+          <span className="select-none text-muted-foreground">$ </span>
+          {normalize(command)}
+        </pre>
+      )}
+      {stdout && (
+        <CollapsiblePre content={normalize(stdout)} className="text-foreground" />
+      )}
+      {stderr && (
+        <CollapsiblePre content={normalize(stderr)} className="text-destructive" />
+      )}
+      {failed && (
+        <div>
+          <span className="sr-only">Command exited with code {exitCode}</span>
+          <span
+            aria-hidden="true"
+            className="inline-block rounded bg-destructive-subtle px-1 py-0.5 text-[10px] font-medium leading-none tabular-nums text-destructive"
+          >
+            exit {exitCode}
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/execution/TodoCard.tsx

@@ -0,0 +1,186 @@
+"use client";
+
+import { memo, useMemo } from "react";
+import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+import { useRenderTracer } from "../internal/dev";
+import { useAutoDisclosure } from "../internal/useAutoDisclosure";
+import { TodoList, findActiveTodo, todoCompletionSummary } from "./TodoList";
+
+/** Props for {@link TodoCard}. */
+export interface TodoCardProps {
+  /**
+   * The agent's todo map for one execution — the proto map shape
+   * (`execution.status.todos`) passed through by reference so a settled
+   * card skips re-renders while siblings stream (DD-009/010).
+   */
+  readonly todos: { readonly [key: string]: TodoItem };
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * The agent's plan, rendered inline in the message thread as a collapsible
+ * card — the Cursor-style "what I'm going to do, and how far I've got"
+ * surface. It is the in-thread home of the todo list that previously lived
+ * in the right-side Plan tab.
+ *
+ * The card chrome matches the rest of the thread's tool cards (a single
+ * neutral {@link https://tailwindcss.com `border-border-prominent`} line) and
+ * wraps the chrome-less {@link TodoList} primitive — the same list the
+ * sub-agent section renders bare, so there is exactly one todo renderer and no
+ * card-in-a-card.
+ *
+ * Disclosure follows the thread's {@link useAutoDisclosure} convention: open
+ * while the plan is active (any item in progress), settling closed once the
+ * plan is fully resolved, with a user's manual toggle always winning. This
+ * keeps an in-flight plan visible and a finished one tidy, mirroring
+ * `ToolRunGroup`/{@link SubAgentSection}.
+ *
+ * `React.memo`'d on the by-reference `todos` map: structural sharing
+ * (`shareTodos`) keeps the reference stable across stream frames, so the card
+ * re-renders only when the plan actually changes — never per frame.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * <TodoCard todos={execution.status?.todos ?? {}} />
+ * ```
+ */
+export const TodoCard = memo(function TodoCard({
+  todos,
+  className,
+}: TodoCardProps) {
+  useRenderTracer("TodoCard", { todos });
+
+  const count = Object.keys(todos).length;
+  const isActive = findActiveTodo(todos) != null;
+  const summary = todoCompletionSummary(todos);
+  const allDone = useMemo(
+    () =>
+      count > 0 &&
+      Object.values(todos).every(
+        (t) =>
+          t.status === TodoStatus.TODO_COMPLETED ||
+          t.status === TodoStatus.TODO_CANCELLED,
+      ),
+    [todos, count],
+  );
+
+  // Open while the plan is being worked, tidy once it is fully resolved; a
+  // manual toggle wins for the card's lifetime. A completed plan in session
+  // history therefore renders collapsed.
+  const [expanded, handleToggle] = useAutoDisclosure(isActive);
+
+  // buildThreadItems only emits this item when todos exist, but guard anyway
+  // so the component is safe to use standalone.
+  if (count === 0) return null;
+
+  return (
+    <div
+      role="region"
+      aria-label="Agent to-dos"
+      data-cursor-target="todo-card"
+      className={cn(
+        "rounded-lg border border-border-prominent overflow-hidden",
+        className,
+      )}
+    >
+      <button
+        type="button"
+        aria-expanded={expanded}
+        onClick={handleToggle}
+        className={cn(
+          "flex w-full cursor-pointer items-center gap-2 px-2.5 py-1.5 text-left text-xs text-muted-foreground transition-colors",
+          "hover:bg-muted-subtle",
+          // ring-inset so the card's overflow-hidden does not clip the focus ring.
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+        )}
+      >
+        <span
+          className={cn(
+            "shrink-0",
+            allDone ? "text-success" : "text-muted-foreground",
+          )}
+          aria-hidden="true"
+        >
+          <PlanIcon />
+        </span>
+        <span className="min-w-0 flex-1 truncate font-medium text-foreground">
+          To-dos
+        </span>
+        {summary && (
+          <span className="shrink-0 tabular-nums text-muted-foreground">
+            {summary}
+          </span>
+        )}
+        <ChevronIcon expanded={expanded} />
+      </button>
+
+      {expanded && (
+        <div className="border-t border-border-muted px-2.5 py-2">
+          <TodoList todos={todos} />
+        </div>
+      )}
+    </div>
+  );
+}, todoCardPropsEqual);
+
+/**
+ * Shallow comparator for {@link TodoCardProps}. The `todos` map is kept
+ * referentially stable by `shareTodos`, so an identity check is exactly the
+ * right (and cheapest) "did the plan change?" test.
+ *
+ * @internal Exported for testing — not part of the public API.
+ */
+export function todoCardPropsEqual(
+  prev: Readonly<TodoCardProps>,
+  next: Readonly<TodoCardProps>,
+): boolean {
+  return prev.todos === next.todos && prev.className === next.className;
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons — kept inline for SDK independence (codebase pattern)
+// ---------------------------------------------------------------------------
+
+function PlanIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M2 3h8M2 6h6M2 9h7" />
+    </svg>
+  );
+}
+
+function ChevronIcon({ expanded }: { expanded: boolean }) {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 10 10"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn(
+        "shrink-0 text-muted-foreground transition-transform duration-150",
+        expanded && "rotate-90",
+      )}
+      aria-hidden="true"
+    >
+      <path d="M3.5 2L6.5 5L3.5 8" />
+    </svg>
+  );
+}

package/src/execution/ToolArgsView.tsx

@@ -9,7 +9,7 @@ import {
 import type { ToolCategory, ToolCategoryInfo } from "./tool-categories";
 import { FilePathLink } from "./FilePathLink";
 import { McpArgsView, McpMetadataRow } from "./McpToolDetail";
-import { useSandboxNormalize } from "./SandboxContext";
+import { TerminalSession } from "./TerminalSession";
 import {
   CollapsibleCode,
   FilePathIcon,
@@ -34,6 +34,12 @@ export interface ToolArgsViewProps {
   readonly args: Record<string, unknown> | null;
   /** MCP server slug for MCP tool classification and metadata. */
   readonly mcpServerSlug?: string;
+  /**
+   * Whether the file-tool view renders the path row. Defaults to `true`. Set to
+   * `false` where an ancestor already names the file (the approval gate header),
+   * so the write/edit content shows without restating the path.
+   */
+  readonly showFileName?: boolean;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
@@ -66,6 +72,7 @@ export function ToolArgsView({
   toolName,
   args,
   mcpServerSlug,
+  showFileName = true,
   className,
 }: ToolArgsViewProps) {
   const categoryInfo = useMemo(
@@ -86,6 +93,7 @@ export function ToolArgsView({
         args={args}
         primaryArg={primaryArg}
         mcpServerSlug={mcpServerSlug}
+        showFileName={showFileName}
       />
     </div>
   );
@@ -101,12 +109,14 @@ function CategoryArgsDispatch({
   args,
   primaryArg,
   mcpServerSlug,
+  showFileName,
 }: {
   category: ToolCategory;
   toolName: string;
   args: Record<string, unknown> | null;
   primaryArg: string | null;
   mcpServerSlug?: string;
+  showFileName: boolean;
 }) {
   switch (category) {
     case "shell":
@@ -117,7 +127,12 @@ function CategoryArgsDispatch({
     case "edit":
     case "delete":
       return primaryArg ? (
-        <FileArgsView path={primaryArg} category={category} args={args} />
+        <FileArgsView
+          path={primaryArg}
+          category={category}
+          args={args}
+          showFileName={showFileName}
+        />
       ) : null;
 
     case "search":
@@ -144,28 +159,22 @@ function CategoryArgsDispatch({
 // Category-specific views
 // ---------------------------------------------------------------------------
 
+// Pre-execution (approval gate) shell view: the command only, in the same
+// terminal chrome the completed call uses — there is no output yet.
 function ShellArgsView({ command }: { command: string }) {
-  const normalize = useSandboxNormalize();
-  return (
-    <div className="rounded-md border border-border bg-[var(--stgm-terminal-bg,#1a1a2e)] p-2.5">
-      <pre className="whitespace-pre-wrap break-words font-mono text-xs text-[var(--stgm-terminal-fg,#e0e0e0)]">
-        <span className="select-none text-[var(--stgm-terminal-prompt,#6b7280)]">
-          ${" "}
-        </span>
-        {normalize(command)}
-      </pre>
-    </div>
-  );
+  return <TerminalSession command={command} />;
 }
 
 function FileArgsView({
   path,
   category,
   args,
+  showFileName = true,
 }: {
   path: string;
   category: string;
   args: Record<string, unknown> | null;
+  showFileName?: boolean;
 }) {
   const writeContent = useMemo(() => {
     if (category !== "write" && category !== "edit") return null;
@@ -175,10 +184,12 @@ function FileArgsView({
 
   return (
     <div className="space-y-1.5">
-      <div className="flex items-center gap-1.5 text-xs">
-        <FilePathIcon />
-        <FilePathLink path={path} className="text-xs" />
-      </div>
+      {showFileName && (
+        <div className="flex items-center gap-1.5 text-xs">
+          <FilePathIcon />
+          <FilePathLink path={path} className="text-xs" />
+        </div>
+      )}
       {writeContent && (
         <CollapsibleCode label="Content" content={writeContent} />
       )}