@stigmer/react 0.3.4 → 0.4.1

package/src/internal/store/structural-share.ts

@@ -0,0 +1,318 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+/**
+ * Compares two `AgentExecution` snapshots and returns a hybrid object
+ * that reuses old references for unchanged subtrees.
+ *
+ * The runner appends new messages and mutates the streaming tail.
+ * Messages at stable indices with unchanged content keep the previous
+ * reference so downstream `React.memo` can skip re-renders.
+ *
+ * When `prev` is `null` (first snapshot), returns `next` unchanged.
+ */
+export function structuralShare(
+  prev: AgentExecution | null,
+  next: AgentExecution,
+): AgentExecution {
+  if (prev === null) return next;
+
+  const prevStatus = prev.status;
+  const nextStatus = next.status;
+
+  if (!prevStatus || !nextStatus) return next;
+
+  const sharedMessages = shareMessages(
+    prevStatus.messages,
+    nextStatus.messages,
+  );
+  const sharedSubAgents = shareSubAgents(
+    prevStatus.subAgentExecutions,
+    nextStatus.subAgentExecutions,
+  );
+  const sharedApprovals = shareApprovals(
+    prevStatus.pendingApprovals,
+    nextStatus.pendingApprovals,
+  );
+  const sharedTodos = shareTodos(prevStatus.todos, nextStatus.todos);
+
+  const messagesUnchanged = sharedMessages === prevStatus.messages;
+  const subAgentsUnchanged = sharedSubAgents === prevStatus.subAgentExecutions;
+  const approvalsUnchanged = sharedApprovals === prevStatus.pendingApprovals;
+  const todosUnchanged = sharedTodos === prevStatus.todos;
+
+  const statusFieldsUnchanged =
+    prevStatus.phase === nextStatus.phase &&
+    prevStatus.error === nextStatus.error &&
+    prevStatus.startedAt === nextStatus.startedAt &&
+    prevStatus.completedAt === nextStatus.completedAt &&
+    prevStatus.runnerId === nextStatus.runnerId;
+
+  if (
+    messagesUnchanged &&
+    subAgentsUnchanged &&
+    approvalsUnchanged &&
+    todosUnchanged &&
+    statusFieldsUnchanged &&
+    prevStatus.artifacts.length === nextStatus.artifacts.length &&
+    prevStatus.workspaceWriteBacks.length ===
+      nextStatus.workspaceWriteBacks.length
+  ) {
+    return prev;
+  }
+
+  const sharedStatus = Object.create(Object.getPrototypeOf(nextStatus));
+  Object.assign(sharedStatus, nextStatus);
+  sharedStatus.messages = sharedMessages;
+  sharedStatus.subAgentExecutions = sharedSubAgents;
+  sharedStatus.pendingApprovals = sharedApprovals;
+  sharedStatus.todos = sharedTodos;
+
+  const sharedExec = Object.create(Object.getPrototypeOf(next));
+  Object.assign(sharedExec, next);
+  sharedExec.status = sharedStatus;
+
+  return sharedExec;
+}
+
+// ---------------------------------------------------------------------------
+// Messages — compare by index (append-only slots)
+// ---------------------------------------------------------------------------
+
+function shareMessages(
+  prev: readonly AgentMessage[],
+  next: readonly AgentMessage[],
+): readonly AgentMessage[] {
+  if (prev.length === 0 && next.length === 0) return prev;
+  if (prev.length === 0) return next;
+
+  let allSame = prev.length === next.length;
+  const result: AgentMessage[] = new Array(next.length);
+
+  for (let i = 0; i < next.length; i++) {
+    if (i < prev.length && messageEqual(prev[i], next[i])) {
+      result[i] = prev[i];
+    } else {
+      result[i] = shareToolCalls(
+        i < prev.length ? prev[i] : null,
+        next[i],
+      );
+      allSame = false;
+    }
+  }
+
+  return allSame ? prev : result;
+}
+
+function messageEqual(a: AgentMessage, b: AgentMessage): boolean {
+  return (
+    a.type === b.type &&
+    a.content === b.content &&
+    a.isStreaming === b.isStreaming &&
+    a.timestamp === b.timestamp &&
+    a.toolCalls.length === b.toolCalls.length &&
+    toolCallsEqual(a.toolCalls, b.toolCalls)
+  );
+}
+
+function toolCallsEqual(
+  a: readonly ToolCall[],
+  b: readonly ToolCall[],
+): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!toolCallEqual(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+/**
+ * When the message itself has changed, try to preserve unchanged
+ * tool call references within it. Returns a new message with the
+ * tool calls array potentially reusing old references.
+ */
+function shareToolCalls(
+  prev: AgentMessage | null,
+  next: AgentMessage,
+): AgentMessage {
+  if (!prev || prev.toolCalls.length === 0 || next.toolCalls.length === 0) {
+    return next;
+  }
+
+  const prevById = new Map<string, ToolCall>();
+  for (const tc of prev.toolCalls) {
+    if (tc.id) prevById.set(tc.id, tc);
+  }
+
+  if (prevById.size === 0) return next;
+
+  let allSame = prev.toolCalls.length === next.toolCalls.length;
+  const shared: ToolCall[] = new Array(next.toolCalls.length);
+
+  for (let i = 0; i < next.toolCalls.length; i++) {
+    const ntc = next.toolCalls[i];
+    const ptc = ntc.id ? prevById.get(ntc.id) : undefined;
+
+    if (ptc && toolCallEqual(ptc, ntc)) {
+      shared[i] = ptc;
+    } else {
+      shared[i] = ntc;
+      allSame = false;
+    }
+  }
+
+  if (allSame) return next;
+
+  const sharedMsg = Object.create(Object.getPrototypeOf(next));
+  Object.assign(sharedMsg, next);
+  sharedMsg.toolCalls = shared;
+  return sharedMsg;
+}
+
+function toolCallEqual(a: ToolCall, b: ToolCall): boolean {
+  return (
+    a.id === b.id &&
+    a.status === b.status &&
+    a.isStreaming === b.isStreaming &&
+    a.result === b.result &&
+    a.completedAt === b.completedAt &&
+    a.error === b.error &&
+    a.name === b.name &&
+    a.argsPreview === b.argsPreview
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Sub-agent executions — compare by `id`
+// ---------------------------------------------------------------------------
+
+function shareSubAgents(
+  prev: readonly SubAgentExecution[],
+  next: readonly SubAgentExecution[],
+): readonly SubAgentExecution[] {
+  if (prev.length === 0 && next.length === 0) return prev;
+  if (prev.length === 0) return next;
+
+  const prevById = new Map<string, SubAgentExecution>();
+  for (const sa of prev) {
+    if (sa.id) prevById.set(sa.id, sa);
+  }
+
+  let allSame = prev.length === next.length;
+  const result: SubAgentExecution[] = new Array(next.length);
+
+  for (let i = 0; i < next.length; i++) {
+    const nsa = next[i];
+    const psa = nsa.id ? prevById.get(nsa.id) : undefined;
+
+    if (psa && subAgentEqual(psa, nsa)) {
+      result[i] = psa;
+    } else if (psa) {
+      result[i] = shareSubAgentMessages(psa, nsa);
+      allSame = false;
+    } else {
+      result[i] = nsa;
+      allSame = false;
+    }
+  }
+
+  return allSame ? prev : result;
+}
+
+function subAgentEqual(a: SubAgentExecution, b: SubAgentExecution): boolean {
+  return (
+    a.id === b.id &&
+    a.status === b.status &&
+    a.output === b.output &&
+    a.error === b.error &&
+    a.completedAt === b.completedAt &&
+    a.messages.length === b.messages.length &&
+    a.subject === b.subject &&
+    subAgentMessagesEqual(a.messages, b.messages)
+  );
+}
+
+function subAgentMessagesEqual(
+  a: readonly AgentMessage[],
+  b: readonly AgentMessage[],
+): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!messageEqual(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+function shareSubAgentMessages(
+  prev: SubAgentExecution,
+  next: SubAgentExecution,
+): SubAgentExecution {
+  const sharedMsgs = shareMessages(prev.messages, next.messages);
+  if (sharedMsgs === prev.messages && subAgentEqual(prev, next)) {
+    return prev;
+  }
+
+  const shared = Object.create(Object.getPrototypeOf(next));
+  Object.assign(shared, next);
+  shared.messages = sharedMsgs;
+  return shared;
+}
+
+// ---------------------------------------------------------------------------
+// Pending approvals — compare by `toolCallId`
+// ---------------------------------------------------------------------------
+
+function shareApprovals(
+  prev: readonly PendingApproval[],
+  next: readonly PendingApproval[],
+): readonly PendingApproval[] {
+  if (prev.length === 0 && next.length === 0) return prev;
+  if (prev.length !== next.length) return next;
+
+  const prevById = new Map<string, PendingApproval>();
+  for (const a of prev) {
+    prevById.set(a.toolCallId, a);
+  }
+
+  for (const na of next) {
+    const pa = prevById.get(na.toolCallId);
+    if (!pa || !approvalEqual(pa, na)) return next;
+  }
+
+  return prev;
+}
+
+function approvalEqual(a: PendingApproval, b: PendingApproval): boolean {
+  return (
+    a.toolCallId === b.toolCallId &&
+    a.toolName === b.toolName &&
+    a.message === b.message &&
+    a.argsPreview === b.argsPreview &&
+    a.requestedAt === b.requestedAt &&
+    a.fromSubAgent === b.fromSubAgent
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Todos — compare by map key
+// ---------------------------------------------------------------------------
+
+function shareTodos(
+  prev: Record<string, unknown>,
+  next: Record<string, unknown>,
+): Record<string, unknown> {
+  const prevKeys = Object.keys(prev);
+  const nextKeys = Object.keys(next);
+
+  if (prevKeys.length === 0 && nextKeys.length === 0) return prev;
+  if (prevKeys.length !== nextKeys.length) return next;
+
+  for (const key of nextKeys) {
+    if (!(key in prev) || prev[key] !== next[key]) return next;
+  }
+
+  return prev;
+}

package/src/internal/stream-controller.ts

@@ -0,0 +1,201 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ConversationStore } from "./store/conversation-store";
+import { isTerminalPhase } from "../execution/execution-phases";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ControllerStage =
+  | "idle"
+  | "connecting"
+  | "streaming"
+  | "complete"
+  | "error";
+
+export type ControllerState =
+  | { readonly stage: "idle" }
+  | { readonly stage: "connecting"; readonly executionId: string }
+  | { readonly stage: "streaming"; readonly executionId: string }
+  | { readonly stage: "complete"; readonly executionId: string }
+  | {
+      readonly stage: "error";
+      readonly executionId: string;
+      readonly error: Error;
+    };
+
+const IDLE: ControllerState = { stage: "idle" };
+
+/**
+ * Callback interface for the stream controller to communicate with
+ * its host (the React hook). All mutations to external state go
+ * through these callbacks.
+ */
+export interface StreamControllerSink {
+  /** Ingest a snapshot into the store (applies structural sharing). */
+  ingestSnapshot(snapshot: AgentExecution): void;
+  /** Transition the store's stream lifecycle state. */
+  setStreamState(state: ControllerState): void;
+}
+
+// ---------------------------------------------------------------------------
+// StreamController
+// ---------------------------------------------------------------------------
+
+/**
+ * Framework-agnostic finite state machine that manages the lifecycle
+ * of a single execution stream subscription.
+ *
+ * Responsibilities:
+ * - Track FSM state transitions (idle → connecting → streaming → complete/error)
+ * - Buffer incoming snapshots and coalesce via `requestAnimationFrame`
+ * - Flush terminal snapshots immediately (no rAF delay)
+ * - Provide abort/reconnect semantics
+ *
+ * This class has no React dependency. It communicates outward through
+ * a {@link StreamControllerSink} and a `scheduleFlush` function
+ * (typically `requestAnimationFrame`).
+ */
+export class StreamController {
+  private _state: ControllerState = IDLE;
+  private _bufferedSnapshot: AgentExecution | null = null;
+  private _rafId: number | null = null;
+  private _sink: StreamControllerSink;
+  private _scheduleFlush: (cb: () => void) => number;
+  private _cancelFlush: (id: number) => void;
+
+  constructor(
+    sink: StreamControllerSink,
+    scheduleFlush: (cb: () => void) => number = typeof requestAnimationFrame !== "undefined"
+      ? requestAnimationFrame
+      : (cb) => setTimeout(cb, 16) as unknown as number,
+    cancelFlush: (id: number) => void = typeof cancelAnimationFrame !== "undefined"
+      ? cancelAnimationFrame
+      : clearTimeout,
+  ) {
+    this._sink = sink;
+    this._scheduleFlush = scheduleFlush;
+    this._cancelFlush = cancelFlush;
+  }
+
+  /** Current FSM state (read-only). */
+  get state(): ControllerState {
+    return this._state;
+  }
+
+  /**
+   * Transition to `connecting` for the given execution ID.
+   * If already active for a different ID, resets first.
+   */
+  start(executionId: string): void {
+    this._cancelPendingFlush();
+    this._bufferedSnapshot = null;
+    this._transition({ stage: "connecting", executionId });
+  }
+
+  /**
+   * Handle an incoming snapshot from the gRPC stream.
+   * Non-terminal snapshots are buffered for rAF coalescing.
+   * Terminal snapshots flush immediately.
+   */
+  handleSnapshot(snapshot: AgentExecution): void {
+    const executionId = this._activeExecutionId();
+    if (!executionId) return;
+
+    const phase =
+      snapshot.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+    const terminal = isTerminalPhase(phase);
+
+    if (terminal) {
+      this._cancelPendingFlush();
+      this._bufferedSnapshot = null;
+      this._sink.ingestSnapshot(snapshot);
+      this._transition({ stage: "complete", executionId });
+    } else {
+      if (this._state.stage === "connecting") {
+        this._transition({ stage: "streaming", executionId });
+      }
+      this._bufferedSnapshot = snapshot;
+      this._scheduleFlushOnce();
+    }
+  }
+
+  /**
+   * Handle stream completion (iterator exhausted without error).
+   * If we still have a buffered snapshot, flush it first.
+   */
+  handleStreamEnd(): void {
+    const executionId = this._activeExecutionId();
+    if (!executionId) return;
+
+    this._flushBuffer();
+    if (this._state.stage !== "complete") {
+      this._transition({ stage: "complete", executionId });
+    }
+  }
+
+  /**
+   * Handle a stream error. Flushes any buffered snapshot first
+   * so the UI shows the last known good state alongside the error.
+   */
+  handleError(error: Error): void {
+    const executionId = this._activeExecutionId();
+    if (!executionId) return;
+
+    this._cancelPendingFlush();
+    this._flushBuffer();
+    this._transition({ stage: "error", executionId, error });
+  }
+
+  /** Reset to idle. Cancels any pending flush. */
+  reset(): void {
+    this._cancelPendingFlush();
+    this._bufferedSnapshot = null;
+    if (this._state.stage !== "idle") {
+      this._transition(IDLE);
+    }
+  }
+
+  /** Whether the controller has a buffered snapshot awaiting flush. */
+  get hasPendingFlush(): boolean {
+    return this._rafId !== null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private
+  // -------------------------------------------------------------------------
+
+  private _activeExecutionId(): string | null {
+    if (this._state.stage === "idle") return null;
+    return this._state.executionId;
+  }
+
+  private _transition(next: ControllerState): void {
+    this._state = next;
+    this._sink.setStreamState(next);
+  }
+
+  private _scheduleFlushOnce(): void {
+    if (this._rafId !== null) return;
+    this._rafId = this._scheduleFlush(() => {
+      this._rafId = null;
+      this._flushBuffer();
+    });
+  }
+
+  private _flushBuffer(): void {
+    if (this._bufferedSnapshot) {
+      const snap = this._bufferedSnapshot;
+      this._bufferedSnapshot = null;
+      this._sink.ingestSnapshot(snap);
+    }
+  }
+
+  private _cancelPendingFlush(): void {
+    if (this._rafId !== null) {
+      this._cancelFlush(this._rafId);
+      this._rafId = null;
+    }
+  }
+}

package/src/internal/useAutoScroll.ts

@@ -0,0 +1,121 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Near-bottom tolerance in pixels. The sentinel is considered visible
+ * (and follow mode stays engaged) when the user is within this distance
+ * of the bottom. Matches the threshold used by the previous scroll
+ * implementation.
+ */
+const NEAR_BOTTOM_MARGIN_PX = 80;
+
+export interface UseAutoScrollReturn {
+  /** Attach to the scrollable container. */
+  readonly scrollRef: React.RefObject<HTMLDivElement | null>;
+  /** Attach to a zero-height div as the last child of the scroll container. */
+  readonly sentinelRef: React.RefObject<HTMLDivElement | null>;
+  /** Attach to a wrapper div around the thread content (ResizeObserver target). */
+  readonly contentRef: React.RefObject<HTMLDivElement | null>;
+  /** True when the thread auto-scrolls to follow new content. */
+  readonly isFollowing: boolean;
+  /** Scroll to the latest content and re-engage follow mode. */
+  readonly jumpToLatest: () => void;
+}
+
+/**
+ * Two-state auto-scroll state machine for chat threads.
+ *
+ * **Following** — content is pinned to the bottom; new content
+ * (streaming tokens, new messages, tool panel expansion) triggers a
+ * `requestAnimationFrame`-batched scroll-to-bottom.
+ *
+ * **Disengaged** — the user scrolled away from the bottom; no
+ * automatic scrolling occurs. Call {@link UseAutoScrollReturn.jumpToLatest}
+ * to re-engage.
+ *
+ * State transitions are driven by an `IntersectionObserver` on a
+ * bottom sentinel element. A `ResizeObserver` on the content wrapper
+ * detects height growth and triggers rAF-batched scroll writes when
+ * in the Following state.
+ *
+ * @internal Not part of the public API.
+ */
+export function useAutoScroll(): UseAutoScrollReturn {
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const sentinelRef = useRef<HTMLDivElement | null>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+
+  const [isFollowing, setIsFollowing] = useState(true);
+  const isFollowingRef = useRef(true);
+  const rafIdRef = useRef(0);
+
+  // Keep ref in sync with state so observer callbacks read the latest
+  // value without re-subscribing on every state change.
+  useEffect(() => {
+    isFollowingRef.current = isFollowing;
+  }, [isFollowing]);
+
+  // --- IntersectionObserver: sentinel visibility drives state ---
+  useEffect(() => {
+    const sentinel = sentinelRef.current;
+    const scroller = scrollRef.current;
+    if (!sentinel || !scroller) return;
+
+    // Establish initial position at the bottom so the first IO
+    // callback sees the sentinel as intersecting.
+    scroller.scrollTop = scroller.scrollHeight;
+
+    const io = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        if (!entry) return;
+        const visible = entry.isIntersecting;
+        isFollowingRef.current = visible;
+        setIsFollowing(visible);
+      },
+      {
+        root: scroller,
+        rootMargin: `0px 0px ${NEAR_BOTTOM_MARGIN_PX}px 0px`,
+        threshold: 0,
+      },
+    );
+
+    io.observe(sentinel);
+    return () => io.disconnect();
+  }, []);
+
+  // --- ResizeObserver: scroll on content height growth while following ---
+  useEffect(() => {
+    const content = contentRef.current;
+    if (!content || !scrollRef.current) return;
+
+    const ro = new ResizeObserver(() => {
+      if (!isFollowingRef.current) return;
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = requestAnimationFrame(() => {
+        const el = scrollRef.current;
+        if (el) el.scrollTop = el.scrollHeight;
+      });
+    });
+
+    ro.observe(content);
+
+    return () => {
+      ro.disconnect();
+      cancelAnimationFrame(rafIdRef.current);
+    };
+  }, []);
+
+  const jumpToLatest = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+    // Eagerly set following — IO callback will confirm when the
+    // sentinel becomes visible after the scroll.
+    isFollowingRef.current = true;
+    setIsFollowing(true);
+  }, []);
+
+  return { scrollRef, sentinelRef, contentRef, isFollowing, jumpToLatest };
+}