@stigmer/react 0.5.0 → 1.0.0

package/src/execution/ContextGauge.tsx

@@ -0,0 +1,243 @@
+"use client";
+
+import { memo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { cn } from "@stigmer/theme";
+import {
+  useContextWindow,
+  type ContextHealth,
+  type UseContextWindowReturn,
+} from "./useContextWindow";
+import { formatTokenCount } from "./UsageWidget";
+
+/** Props for {@link ContextGauge}. */
+export interface ContextGaugeProps {
+  /**
+   * The execution snapshot from `useExecutionStream`, or `null`.
+   * The gauge extracts `context_info` from the execution status.
+   */
+  readonly execution: AgentExecution | null;
+  /**
+   * When `true`, renders a minimal bar without labels.
+   * Use in tight layouts (e.g., inline status indicators).
+   * @default false
+   */
+  readonly compact?: boolean;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+const HEALTH_BAR_COLORS: Record<ContextHealth, string> = {
+  healthy: "bg-success",
+  warning: "bg-warning",
+  critical: "bg-destructive",
+};
+
+const HEALTH_TEXT_COLORS: Record<ContextHealth, string> = {
+  healthy: "text-success",
+  warning: "text-warning",
+  critical: "text-destructive",
+};
+
+const HEALTH_LABELS: Record<ContextHealth, string> = {
+  healthy: "Healthy",
+  warning: "Approaching limit",
+  critical: "Near limit",
+};
+
+function formatCompactTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${Math.round(count / 1_000)}K`;
+  return String(count);
+}
+
+/**
+ * Visual gauge showing context window utilization during agent execution.
+ *
+ * Renders a progress bar with threshold markers, token count labels, and
+ * a health indicator derived from utilization percentage. The gauge updates
+ * in real-time as the execution streams status updates.
+ *
+ * Returns `null` when `context_info` is absent (e.g., Cursor harness
+ * where context is managed externally).
+ *
+ * All visual properties flow through `--stgm-*` tokens. Zero Console
+ * dependencies. Accessible via `role="meter"` with ARIA value attributes.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * <ContextGauge execution={execution} />
+ * ```
+ *
+ * @example Compact mode in a status bar:
+ * ```tsx
+ * <ContextGauge execution={execution} compact />
+ * ```
+ *
+ * @see {@link useContextWindow} - headless hook for custom rendering
+ */
+export const ContextGauge = memo(function ContextGauge({
+  execution,
+  compact = false,
+  className,
+}: ContextGaugeProps) {
+  const ctx = useContextWindow(execution);
+
+  if (!ctx.hasContextInfo) return null;
+
+  if (compact) return <CompactGauge ctx={ctx} className={className} />;
+
+  return <FullGauge ctx={ctx} className={className} />;
+});
+
+const CompactGauge = memo(function CompactGauge({
+  ctx,
+  className,
+}: {
+  readonly ctx: UseContextWindowReturn;
+  readonly className?: string;
+}) {
+  const barPercent = Math.min(ctx.utilizationPercent, 100);
+
+  return (
+    <div
+      role="meter"
+      aria-label="Context window utilization"
+      aria-valuenow={ctx.currentTokenCount}
+      aria-valuemin={0}
+      aria-valuemax={ctx.contextWindowLimit}
+      aria-valuetext={`${Math.round(ctx.utilizationPercent)}% context used`}
+      className={cn("flex items-center gap-2", className)}
+    >
+      <div className="h-1.5 flex-1 overflow-hidden rounded-full bg-muted">
+        <div
+          className={cn(
+            "h-full rounded-full transition-colors",
+            HEALTH_BAR_COLORS[ctx.health],
+          )}
+          style={{ width: `${barPercent}%` }}
+        />
+      </div>
+      <span
+        className={cn(
+          "shrink-0 text-xs tabular-nums",
+          HEALTH_TEXT_COLORS[ctx.health],
+        )}
+      >
+        {Math.round(ctx.utilizationPercent)}%
+      </span>
+    </div>
+  );
+});
+
+const FullGauge = memo(function FullGauge({
+  ctx,
+  className,
+}: {
+  readonly ctx: UseContextWindowReturn;
+  readonly className?: string;
+}) {
+  const barPercent = Math.min(ctx.utilizationPercent, 100);
+  const triggerPercent =
+    ctx.triggerThreshold > 0 && ctx.contextWindowLimit > 0
+      ? (ctx.triggerThreshold / ctx.contextWindowLimit) * 100
+      : 0;
+
+  return (
+    <div
+      role="meter"
+      aria-label="Context window utilization"
+      aria-valuenow={ctx.currentTokenCount}
+      aria-valuemin={0}
+      aria-valuemax={ctx.contextWindowLimit}
+      aria-valuetext={`${formatCompactTokens(ctx.currentTokenCount)} of ${formatCompactTokens(ctx.contextWindowLimit)} tokens used, ${Math.round(ctx.utilizationPercent)}%`}
+      className={cn("flex flex-col gap-1.5", className)}
+    >
+      {/* Header: label + percentage */}
+      <div className="flex items-baseline justify-between">
+        <span className="text-xs font-medium text-foreground">
+          Context
+        </span>
+        <span
+          className={cn(
+            "text-xs tabular-nums font-medium",
+            HEALTH_TEXT_COLORS[ctx.health],
+          )}
+        >
+          {Math.round(ctx.utilizationPercent)}%
+        </span>
+      </div>
+
+      {/* Progress bar with threshold marker */}
+      <div className="relative">
+        <div className="h-2 overflow-hidden rounded-full bg-muted">
+          <div
+            className={cn(
+              "h-full rounded-full transition-colors",
+              HEALTH_BAR_COLORS[ctx.health],
+            )}
+            style={{ width: `${barPercent}%` }}
+          />
+        </div>
+        {triggerPercent > 0 && triggerPercent < 100 && (
+          <div
+            className="absolute top-0 h-2 w-px bg-muted-foreground/40"
+            style={{ left: `${triggerPercent}%` }}
+            aria-hidden="true"
+          />
+        )}
+      </div>
+
+      {/* Token counts */}
+      <div className="text-xs tabular-nums text-muted-foreground">
+        {formatCompactTokens(ctx.currentTokenCount)} /{" "}
+        {formatCompactTokens(ctx.contextWindowLimit)} tokens
+      </div>
+
+      {/* Health status + summarization count */}
+      <div className="flex items-center gap-1.5">
+        <span
+          className={cn(
+            "inline-flex h-1.5 w-1.5 rounded-full",
+            HEALTH_BAR_COLORS[ctx.health],
+          )}
+          aria-hidden="true"
+        />
+        <span className="text-xs text-muted-foreground">
+          {HEALTH_LABELS[ctx.health]}
+        </span>
+        {ctx.summarizationEvents.length > 0 && (
+          <span className="text-xs text-muted-foreground">
+            · {ctx.summarizationEvents.length}{" "}
+            {ctx.summarizationEvents.length === 1
+              ? "summarization"
+              : "summarizations"}
+          </span>
+        )}
+      </div>
+
+      {/* Summarization details (when events exist) */}
+      {ctx.summarizationEvents.length > 0 && (
+        <SummarizationSummary events={ctx.summarizationEvents} />
+      )}
+    </div>
+  );
+});
+
+function SummarizationSummary({
+  events,
+}: {
+  readonly events: UseContextWindowReturn["summarizationEvents"];
+}) {
+  const latest = events[events.length - 1];
+  if (!latest) return null;
+
+  return (
+    <div className="pl-3 text-xs tabular-nums text-muted-foreground">
+      Last: {formatTokenCount(latest.tokensBefore)} →{" "}
+      {formatTokenCount(latest.tokensAfter)} tokens (
+      {Math.round(latest.compressionRatio * 100)}% reduction)
+    </div>
+  );
+}

package/src/execution/InteractionModeBadge.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { memo } from "react";
+import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link InteractionModeBadge}. */
+export interface InteractionModeBadgeProps {
+  /** The interaction mode to display. */
+  readonly mode: InteractionMode;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Displays the interaction mode of an execution as a compact inline badge.
+ *
+ * Only renders for non-default modes (PLAN). Returns `null` for AGENT
+ * and UNSPECIFIED since agent mode is the default and does not need
+ * visual distinction.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * <InteractionModeBadge mode={InteractionMode.PLAN} />
+ * ```
+ */
+export const InteractionModeBadge = memo(function InteractionModeBadge({
+  mode,
+  className,
+}: InteractionModeBadgeProps) {
+  if (
+    mode !== InteractionMode.PLAN
+  ) {
+    return null;
+  }
+
+  return (
+    <span
+      role="status"
+      aria-label="Plan mode"
+      className={cn(
+        "inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 text-[0.65rem] font-medium",
+        "bg-accent text-muted-foreground",
+        className,
+      )}
+    >
+      <PlanIcon />
+      Plan
+    </span>
+  );
+});
+
+function PlanIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M2 3h8M2 6h5M2 9h6" />
+    </svg>
+  );
+}

package/src/execution/MessageThread.tsx

@@ -10,6 +10,7 @@ import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentex
 import {
   ApprovalAction,
   ExecutionPhase,
+  InteractionMode,
   MessageType,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
@@ -21,6 +22,9 @@ import { SubAgentSection } from "./SubAgentSection";
 import { ExecutionPhaseBadge } from "./ExecutionPhaseBadge";
 import { SetupProgress } from "./SetupProgress";
 import { ApprovalCard } from "./ApprovalCard";
+import { SummarizationCard } from "./SummarizationCard";
+import { PlanCompletionCard } from "./PlanCompletionCard";
+import type { SummarizationEventView } from "./useContextWindow";
 import { FilePathContext, type FilePathContextValue } from "./FilePathContext";
 import type { ResolvedPathAction } from "./file-path-resolver";
 import { SandboxContext, type SandboxContextValue } from "./SandboxContext";
@@ -103,6 +107,14 @@ export interface MessageThreadProps {
    * the user's own filesystem (no normalization needed).
    */
   readonly sandboxWorkspaceRoot?: string;
+  /**
+   * Summarization events from context window tracking. When provided,
+   * "Context compacted" cards are interleaved into the thread at the
+   * correct chronological position based on event timestamps.
+   *
+   * Obtain from {@link useContextWindow}.summarizationEvents.
+   */
+  readonly summarizationEvents?: readonly SummarizationEventView[];
   /**
    * Enable virtualized rendering for long conversations. Requires
    * `react-virtuoso` to be installed as a peer dependency. When
@@ -112,6 +124,19 @@ export interface MessageThreadProps {
    * @default false
    */
   readonly virtualized?: boolean;
+  /**
+   * Called when the user clicks "Implement" on a completed Plan-mode
+   * execution's {@link PlanCompletionCard}.
+   *
+   * When provided, a CTA card is rendered at the end of the thread
+   * after a Plan-mode execution completes successfully. The consumer
+   * typically wires this to switch the interaction mode to Agent,
+   * pre-fill the composer, and focus it.
+   *
+   * When omitted, no plan completion card is rendered. Backward
+   * compatible — existing consumers see no change.
+   */
+  readonly onBuildFromPlan?: () => void;
 }
 
 /**
@@ -129,7 +154,9 @@ export type ThreadItem =
   | { readonly kind: "sub-agent"; readonly subAgentExecution: SubAgentExecution; readonly key: string }
   | { readonly kind: "phase-badge"; readonly phase: ExecutionPhase; readonly key: string }
   | { readonly kind: "approval-request"; readonly pendingApproval: PendingApproval; readonly key: string }
-  | { readonly kind: "setup-progress"; readonly workspaceEntries: readonly WorkspaceEntry[]; readonly serverPhase?: string; readonly isAwaitingResponse?: boolean; readonly key: string };
+  | { readonly kind: "setup-progress"; readonly workspaceEntries: readonly WorkspaceEntry[]; readonly serverPhase?: string; readonly isAwaitingResponse?: boolean; readonly key: string }
+  | { readonly kind: "context-compacted"; readonly event: SummarizationEventView; readonly key: string }
+  | { readonly kind: "plan-completion"; readonly key: string };
 
 function hasAiMessages(execution: AgentExecution): boolean {
   const messages = execution.status?.messages;
@@ -154,6 +181,7 @@ export function buildThreadItems(
   pendingUserMessage: string | null | undefined,
   includeApprovals: boolean,
   workspaceEntries: readonly WorkspaceEntry[] | undefined,
+  summarizationEvents?: readonly SummarizationEventView[],
 ): ThreadItem[] {
   const items: ThreadItem[] = [];
   const allExecutions = activeStreamExecution
@@ -163,6 +191,30 @@ export function buildThreadItems(
     ? allExecutions.length - 1
     : -1;
 
+  // Build a queue of summarization events to interleave by timestamp.
+  // Events are consumed as messages pass their timestamp.
+  const pendingEvents = summarizationEvents?.length
+    ? [...summarizationEvents]
+    : [];
+  let eventCursor = 0;
+
+  function flushEventsUntil(messageTimestamp: string | undefined): void {
+    if (!messageTimestamp || pendingEvents.length === 0) return;
+    while (
+      eventCursor < pendingEvents.length &&
+      pendingEvents[eventCursor].timestamp &&
+      pendingEvents[eventCursor].timestamp <= messageTimestamp
+    ) {
+      const evt = pendingEvents[eventCursor];
+      items.push({
+        kind: "context-compacted",
+        event: evt,
+        key: `compacted-${evt.timestamp}`,
+      });
+      eventCursor++;
+    }
+  }
+
   for (let ei = 0; ei < allExecutions.length; ei++) {
     const exec = allExecutions[ei];
     const execId = exec.metadata?.id ?? `_e${ei}`;
@@ -198,6 +250,8 @@ export function buildThreadItems(
       // to their parent MESSAGE_AI and rendered via ToolCallGroup.
       if (msg.type === MessageType.MESSAGE_TOOL) continue;
 
+      flushEventsUntil(msg.timestamp);
+
       const isEmptyAi =
         msg.type === MessageType.MESSAGE_AI && !msg.content.trim();
 
@@ -253,6 +307,17 @@ export function buildThreadItems(
     }
   }
 
+  // Flush any remaining summarization events that occurred after all messages
+  while (eventCursor < pendingEvents.length) {
+    const evt = pendingEvents[eventCursor];
+    items.push({
+      kind: "context-compacted",
+      event: evt,
+      key: `compacted-${evt.timestamp}`,
+    });
+    eventCursor++;
+  }
+
   const lastExec = allExecutions[allExecutions.length - 1];
   const lastPhase =
     lastExec?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
@@ -294,6 +359,13 @@ export function buildThreadItems(
     });
   }
 
+  if (
+    lastPhase === ExecutionPhase.EXECUTION_COMPLETED &&
+    lastExec?.spec?.executionConfig?.interactionMode === InteractionMode.PLAN
+  ) {
+    items.push({ kind: "plan-completion", key: "plan-completion" });
+  }
+
   if (includeApprovals) {
     const allApprovals = lastExec?.status?.pendingApprovals ?? [];
     for (let ai = 0; ai < allApprovals.length; ai++) {
@@ -359,14 +431,16 @@ export function MessageThread({
   workspaceEntries,
   onFilePathClick,
   sandboxWorkspaceRoot,
+  summarizationEvents,
   virtualized = false,
+  onBuildFromPlan,
 }: MessageThreadProps) {
   useRenderTracer("MessageThread", { executions, activeStreamExecution });
 
   const includeApprovals = onApprovalSubmit != null;
   const items = useMemo(
-    () => buildThreadItems(executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries),
-    [executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries],
+    () => buildThreadItems(executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents),
+    [executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents],
   );
 
   useKeyStability(items);
@@ -395,6 +469,7 @@ export function MessageThread({
             submittingApprovalIds={submittingApprovalIds}
             filePathCtx={filePathCtx}
             sandboxCtx={sandboxCtx}
+            onBuildFromPlan={onBuildFromPlan}
           />
         </Suspense>
       </div>
@@ -410,6 +485,7 @@ export function MessageThread({
       submittingApprovalIds={submittingApprovalIds}
       filePathCtx={filePathCtx}
       sandboxCtx={sandboxCtx}
+      onBuildFromPlan={onBuildFromPlan}
     />
   );
 }
@@ -430,6 +506,7 @@ interface NonVirtualizedThreadProps {
   readonly submittingApprovalIds?: ReadonlySet<string>;
   readonly filePathCtx: FilePathContextValue;
   readonly sandboxCtx: SandboxContextValue;
+  readonly onBuildFromPlan?: () => void;
 }
 
 function NonVirtualizedThread({
@@ -440,6 +517,7 @@ function NonVirtualizedThread({
   submittingApprovalIds,
   filePathCtx,
   sandboxCtx,
+  onBuildFromPlan,
 }: NonVirtualizedThreadProps) {
   const { scrollRef, sentinelRef, contentRef, isFollowing, jumpToLatest } =
     useAutoScroll();
@@ -472,6 +550,7 @@ function NonVirtualizedThread({
                   formatToolCallSummary={formatToolCallSummary}
                   onApprovalSubmit={onApprovalSubmit}
                   submittingApprovalIds={submittingApprovalIds}
+                  onBuildFromPlan={onBuildFromPlan}
                 />
               </ThreadItemWrapper>
             ))}
@@ -505,6 +584,7 @@ export interface ThreadItemRendererProps {
     comment?: string,
   ) => void;
   readonly submittingApprovalIds?: ReadonlySet<string>;
+  readonly onBuildFromPlan?: () => void;
 }
 
 /**
@@ -523,6 +603,7 @@ export function ThreadItemRenderer({
   formatToolCallSummary,
   onApprovalSubmit,
   submittingApprovalIds,
+  onBuildFromPlan,
 }: ThreadItemRendererProps) {
   switch (item.kind) {
     case "message":
@@ -570,6 +651,10 @@ export function ThreadItemRenderer({
           isAwaitingResponse={item.isAwaitingResponse}
         />
       );
+    case "context-compacted":
+      return <SummarizationCard event={item.event} />;
+    case "plan-completion":
+      return <PlanCompletionCard onImplement={onBuildFromPlan} />;
   }
 }
 

package/src/execution/PlanCompletionCard.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link PlanCompletionCard}. */
+export interface PlanCompletionCardProps {
+  /** Called when the user clicks the "Implement" button. */
+  readonly onImplement?: () => void;
+  /** Disables the CTA button (e.g., while an execution is active). */
+  readonly disabled?: boolean;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+/**
+ * Inline CTA card shown in the {@link MessageThread} after a completed
+ * Plan-mode execution.
+ *
+ * Offers a single "Implement" action that the consumer wires to switch
+ * the interaction mode to Agent, pre-fill the composer, and focus it.
+ *
+ * Renders nothing when `onImplement` is not provided, so the card is
+ * fully opt-in from the consumer's perspective.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ */
+export const PlanCompletionCard = memo(function PlanCompletionCard({
+  onImplement,
+  disabled,
+  className,
+}: PlanCompletionCardProps) {
+  if (!onImplement) return null;
+
+  return (
+    <div
+      role="status"
+      aria-label="Plan complete"
+      className={cn(
+        "mx-4 flex items-center gap-3 rounded-md border border-border/50",
+        "bg-muted/30 px-3 py-2.5",
+        className,
+      )}
+    >
+      <PlanCompleteIcon />
+      <span className="min-w-0 flex-1 text-xs font-medium text-muted-foreground">
+        Plan complete — ready to implement?
+      </span>
+      <button
+        type="button"
+        disabled={disabled}
+        onClick={onImplement}
+        className={cn(
+          "inline-flex items-center gap-1.5 rounded-md px-3 py-1.5",
+          "text-xs font-medium transition-colors",
+          "bg-primary text-primary-foreground",
+          "hover:bg-primary-hover",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          "disabled:pointer-events-none disabled:opacity-50",
+        )}
+      >
+        <ImplementIcon />
+        Implement
+      </button>
+    </div>
+  );
+});
+
+function PlanCompleteIcon() {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground/70"
+      aria-hidden="true"
+    >
+      <path d="M3 4h10M3 8h7M3 12h8" />
+      <path d="M12.5 10.5l1.5 1.5-1.5 1.5" />
+    </svg>
+  );
+}
+
+function ImplementIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M2 6h8M7 3l3 3-3 3" />
+    </svg>
+  );
+}