@stigmer/react 1.0.4 → 2.0.1

package/src/session/inspector/useSessionInspector.ts

@@ -0,0 +1,171 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { TabItem } from "../../tabs/Tabs";
+import { isTerminalPhase } from "../../execution/execution-phases";
+import type { SelectedThreadItem } from "../../internal/store/selection-store";
+
+export type SessionInspectorTabId =
+  | "workspace"
+  | "configure"
+  | "plan"
+  | "changes"
+  | "artifacts"
+  | "usage"
+  | "inspect";
+
+export interface UseSessionInspectorOptions {
+  readonly phase: ExecutionPhase | null;
+  readonly hasWriteBacks: boolean;
+  readonly writeBackCount: number;
+  readonly hasArtifacts: boolean;
+  readonly artifactCount: number;
+  readonly hasUsage: boolean;
+  readonly selectedItem: SelectedThreadItem | null;
+}
+
+export interface UseSessionInspectorReturn {
+  readonly tabs: readonly TabItem[];
+  readonly activeTab: SessionInspectorTabId;
+  readonly onTabChange: (tabId: string) => void;
+}
+
+/**
+ * Compute the system-suggested tab from execution phase and selection.
+ *
+ * Priority:
+ * 1. Thread item selected -> "inspect"
+ * 2. No execution or terminal phase (idle / ready for follow-up) -> "workspace"
+ * 3. Actively running -> "plan"
+ */
+function deriveAutoTab(
+  phase: ExecutionPhase | null,
+  selectedItem: SelectedThreadItem | null,
+): SessionInspectorTabId {
+  if (selectedItem) return "inspect";
+  if (phase === null || isTerminalPhase(phase)) return "workspace";
+  return "plan";
+}
+
+/**
+ * Build the contextual tab list with badges.
+ *
+ * Tab order follows the user's mental model — context before output:
+ * Workspace → Config → Plan → Usage. Changes and Artifacts appear
+ * after Plan when data exists; Inspect appears last when a thread item
+ * is selected.
+ */
+export function buildVisibleTabs(opts: {
+  hasWriteBacks: boolean;
+  writeBackCount: number;
+  hasArtifacts: boolean;
+  artifactCount: number;
+  hasUsage: boolean;
+  selectedItem: SelectedThreadItem | null;
+}): TabItem[] {
+  const tabs: TabItem[] = [
+    { id: "workspace", label: "Workspace" },
+    { id: "configure", label: "Config" },
+    { id: "plan", label: "Plan" },
+  ];
+
+  if (opts.hasWriteBacks) {
+    tabs.push({
+      id: "changes",
+      label: "Changes",
+      badge: opts.writeBackCount,
+    });
+  }
+
+  if (opts.hasArtifacts) {
+    tabs.push({
+      id: "artifacts",
+      label: "Artifacts",
+      badge: opts.artifactCount,
+    });
+  }
+
+  tabs.push({ id: "usage", label: "Usage" });
+
+  if (opts.selectedItem) {
+    tabs.push({ id: "inspect", label: "Inspect" });
+  }
+
+  return tabs;
+}
+
+/**
+ * Behavior hook for SessionInspector tab state management.
+ *
+ * Uses the "adjust state during render" pattern from the workflow
+ * `ExecutionInspector`: shadow `prevPhase`/`prevSelected` state,
+ * `userPickedTabRef` for sticky manual picks, and `deriveAutoTab`
+ * for system suggestions. Keeps the user's tab pick sticky until
+ * a meaningful state change resets it.
+ */
+export function useSessionInspector(
+  opts: UseSessionInspectorOptions,
+): UseSessionInspectorReturn {
+  const { phase, hasWriteBacks, writeBackCount, hasArtifacts, artifactCount, hasUsage, selectedItem } = opts;
+
+  const tabs = buildVisibleTabs({ hasWriteBacks, writeBackCount, hasArtifacts, artifactCount, hasUsage, selectedItem });
+
+  const [activeTab, setActiveTab] = useState<SessionInspectorTabId>(
+    () => deriveAutoTab(phase, selectedItem),
+  );
+  const [prevPhase, setPrevPhase] = useState(phase);
+  const [prevSelected, setPrevSelected] = useState(selectedItem);
+  const [prevHasWriteBacks, setPrevHasWriteBacks] = useState(hasWriteBacks);
+  const userPickedTabRef = useRef(false);
+
+  // Selection changed → auto-switch to inspect (unless user picked)
+  if (selectedItem !== prevSelected) {
+    setPrevSelected(selectedItem);
+    if (selectedItem && !userPickedTabRef.current) {
+      setActiveTab("inspect");
+    }
+    if (!selectedItem && activeTab === "inspect") {
+      setActiveTab(deriveAutoTab(phase, null));
+      userPickedTabRef.current = false;
+    }
+  }
+
+  // Phase changed → reset user pick if transitioning from non-terminal to terminal or vice versa
+  if (phase !== prevPhase) {
+    const wasTerminal = prevPhase !== null && isTerminalPhase(prevPhase);
+    const isNowTerminal = phase !== null && isTerminalPhase(phase);
+    setPrevPhase(phase);
+    if (wasTerminal !== isNowTerminal) {
+      userPickedTabRef.current = false;
+      setActiveTab(deriveAutoTab(phase, selectedItem));
+    }
+  }
+
+  // First write-back arrived → auto-switch to changes
+  if (hasWriteBacks && !prevHasWriteBacks) {
+    setPrevHasWriteBacks(hasWriteBacks);
+    if (!userPickedTabRef.current) {
+      setActiveTab("changes");
+    }
+  }
+  if (hasWriteBacks !== prevHasWriteBacks) {
+    setPrevHasWriteBacks(hasWriteBacks);
+  }
+
+  // Ensure active tab is valid (the selected tab may have been removed)
+  const effectiveTab = tabs.some((t) => t.id === activeTab)
+    ? activeTab
+    : deriveAutoTab(phase, selectedItem);
+
+  const onTabChange = useCallback((tabId: string) => {
+    userPickedTabRef.current = true;
+    setActiveTab(tabId as SessionInspectorTabId);
+  }, []);
+
+  return {
+    tabs,
+    activeTab: effectiveTab,
+    onTabChange,
+  };
+}

package/src/session/useCreateSession.ts

@@ -10,6 +10,9 @@ import {
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 import { toProtoHarness, type HarnessOption } from "../models/harness";
+import { toProtoExecutionTarget, type ExecutionTargetOption } from "./execution-target";
+import { useExecutionTarget } from "../execution-target-context";
+import { useRunnerAdapter } from "../runner-adapter";
 
 /** Shared fields present in both variants of {@link CreateSessionInput}. */
 export interface SharedSessionFields {
@@ -23,14 +26,6 @@ export interface SharedSessionFields {
   readonly mcpServerUsages?: McpServerUsageInput[];
   /** Skill references to enable for executions in this session. */
   readonly skillRefs?: ResourceRef[];
-  /**
-   * Runner to bind this session to.
-   *
-   * When set, all executions in the session are routed to this runner's
-   * task queue. When omitted, the backend auto-selects a runner (session
-   * auto-bind in OSS, cloud auto-provisioning in Cloud).
-   */
-  readonly runnerId?: string;
   /**
    * Execution harness for this session.
    *
@@ -38,6 +33,18 @@ export interface SharedSessionFields {
    * Immutable after the first execution runs. Defaults to `"native"`.
    */
   readonly harness?: HarnessOption;
+  /**
+   * Where session activities are executed.
+   *
+   * - `"local"` — Client's embedded runner (desktop app or CLI) polls
+   *   the session's task queue.
+   * - `"cloud"` — Server provisions a cloud sandbox with a runner.
+   * - `undefined` — Server decides based on deployment context
+   *   (LOCAL for OSS, CLOUD for managed).
+   *
+   * Immutable after the first execution runs.
+   */
+  readonly executionTarget?: ExecutionTargetOption;
 }
 
 /**
@@ -122,6 +129,8 @@ export interface UseCreateSessionReturn {
  */
 export function useCreateSession(): UseCreateSessionReturn {
   const stigmer = useStigmer();
+  const contextTarget = useExecutionTarget();
+  const adapter = useRunnerAdapter();
   const [isCreating, setIsCreating] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -156,6 +165,8 @@ export function useCreateSession(): UseCreateSessionReturn {
           );
         }
 
+        const resolvedTarget = input.executionTarget ?? contextTarget;
+
         const session = await stigmer.session.create({
           name: `session-${Date.now()}`,
           org: input.org,
@@ -163,12 +174,20 @@ export function useCreateSession(): UseCreateSessionReturn {
           workspaceEntries: input.workspaceEntries,
           mcpServerUsages: input.mcpServerUsages,
           skillRefs: input.skillRefs,
-          runnerId: input.runnerId,
           agentInstanceId: resolvedInstanceId,
           harness: input.harness ? toProtoHarness(input.harness) : undefined,
+          executionTarget: resolvedTarget
+            ? toProtoExecutionTarget(resolvedTarget)
+            : undefined,
         });
 
-        return { sessionId: session.metadata!.id };
+        const sessionId = session.metadata!.id;
+
+        if (adapter && resolvedTarget === "local") {
+          await adapter.onSessionCreated(sessionId);
+        }
+
+        return { sessionId };
       } catch (err) {
         setError(toError(err));
         throw err;
@@ -176,7 +195,7 @@ export function useCreateSession(): UseCreateSessionReturn {
         setIsCreating(false);
       }
     },
-    [stigmer],
+    [stigmer, contextTarget, adapter],
   );
 
   return { create, isCreating, error, clearError };

package/src/session/useNewSessionFlow.ts

@@ -10,15 +10,15 @@ import { DEFAULT_HARNESS, type HarnessOption } from "../models/harness";
 import { useWorkspaceEntries, type UseWorkspaceEntriesReturn } from "../workspace";
 import { useSessionVariables, type UseSessionVariablesReturn } from "../execution/useSessionVariables";
 import type { SessionComposerSubmitContext } from "../composer";
-import { useRunnerList } from "../runner/useRunnerList";
 import { withTimeout } from "../internal/withTimeout";
 import { useCreateSession } from "./useCreateSession";
 import { useCreateAgentExecution } from "../execution/useCreateAgentExecution";
+import type { ExecutionTargetOption } from "./execution-target";
+import { useExecutionTarget } from "../execution-target-context";
 
 const DEFAULT_AGENT_TIMEOUT_MS = 10_000;
 
 const STORAGE_KEY_HARNESS = "stigmer:session:harness";
-const STORAGE_KEY_RUNNER = "stigmer:session:runner";
 
 function modelStorageKey(harness: HarnessOption): string {
   return harness === "cursor"
@@ -41,6 +41,19 @@ export interface UseNewSessionFlowOptions {
    * If not provided, errors are still available via {@link UseNewSessionFlowReturn.submitError}.
    */
   readonly onError?: (message: string) => void;
+  /**
+   * Where session activities should execute.
+   *
+   * @deprecated Prefer setting `executionTarget` on `StigmerProvider`
+   * instead. The provider-level value is inherited by all hooks in the
+   * tree automatically. This per-hook option is honored as an override
+   * for backward compatibility but will be removed in a future major.
+   *
+   * When omitted, the hook reads from `StigmerProvider`'s
+   * `executionTarget` prop via context. If that is also unset, the
+   * server decides based on deployment context.
+   */
+  readonly executionTarget?: ExecutionTargetOption;
 }
 
 /** Return value of {@link useNewSessionFlow}. */
@@ -75,11 +88,6 @@ export interface UseNewSessionFlowReturn {
   /** Update skill references. */
   readonly setSkillRefs: (refs: ResourceRef[]) => void;
 
-  /** Selected runner ID, or `null` for auto-selection. */
-  readonly runnerId: string | null;
-  /** Update the selected runner. */
-  readonly setRunnerId: (id: string | null) => void;
-
   /** Workspace entries manager (git repos and local paths). */
   readonly workspace: UseWorkspaceEntriesReturn;
   /** Session variables (per-execution secrets) manager. */
@@ -94,7 +102,7 @@ export interface UseNewSessionFlowReturn {
    * Create a session with the first execution.
    *
    * Composes all managed state (agent, workspace, MCP servers, skills,
-   * runner, model, session variables) into the session and execution
+   * model, session variables) into the session and execution
    * creation RPCs, then calls `onSessionCreated` on success.
    *
    * The `model` parameter overrides `modelId` for this submission only
@@ -112,7 +120,7 @@ export interface UseNewSessionFlowReturn {
  *
  * Manages all the state required to configure and submit a new session:
  * model selection (with localStorage persistence), agent resolution,
- * MCP server/skill/runner selection, workspace entries, and session
+ * MCP server/skill selection, workspace entries, and session
  * variables. On submission, creates the session and its first execution
  * in sequence, then notifies the consumer via `onSessionCreated`.
  *
@@ -140,9 +148,7 @@ export interface UseNewSessionFlowReturn {
  *   onMcpServerUsagesChange={flow.setMcpServerUsages}
  *   skillRefs={flow.skillRefs}
  *   onSkillRefsChange={flow.setSkillRefs}
- *   runnerId={flow.runnerId}
- *   onRunnerIdChange={flow.setRunnerId}
- *   sessionVariables={flow.sessionVariables}
+   *   sessionVariables={flow.sessionVariables}
  *   defaultModelId={flow.modelId}
  *   onModelChange={flow.setModelId}
  * />
@@ -152,6 +158,8 @@ export function useNewSessionFlow(
   options: UseNewSessionFlowOptions,
 ): UseNewSessionFlowReturn {
   const { org, onSessionCreated, onError } = options;
+  const contextTarget = useExecutionTarget();
+  const executionTarget = options.executionTarget ?? contextTarget;
 
   const [harness, setHarnessRaw] = useState<HarnessOption>(() => {
     if (typeof window === "undefined") return DEFAULT_HARNESS;
@@ -160,7 +168,6 @@ export function useNewSessionFlow(
   });
 
   const { getModel, isLoading: isModelsLoading } = useModelRegistry({ harness });
-  const { runners, isLoading: isRunnersLoading } = useRunnerList(org);
   const { create: createSession } = useCreateSession();
   const { create: createExecution } = useCreateAgentExecution();
   const {
@@ -177,7 +184,6 @@ export function useNewSessionFlow(
   const [resolution, setResolution] = useState<AgentResolution | null>(null);
   const [mcpServerUsages, setMcpServerUsages] = useState<McpServerUsageInput[]>([]);
   const [skillRefs, setSkillRefs] = useState<ResourceRef[]>([]);
-  const [runnerId, setRunnerId] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [submitError, setSubmitError] = useState<string | null>(null);
 
@@ -220,30 +226,6 @@ export function useNewSessionFlow(
     }
   }, [modelId, harness]);
 
-  // Restore persisted runner — validate against the live runner list.
-  // If the stored runner no longer exists, discard it and clean up localStorage.
-  useEffect(() => {
-    if (isRunnersLoading) return;
-    const stored = localStorage.getItem(STORAGE_KEY_RUNNER);
-    if (!stored) return;
-
-    const exists = runners.some((r) => r.metadata?.id === stored);
-    if (exists) {
-      setRunnerId(stored);
-    } else {
-      localStorage.removeItem(STORAGE_KEY_RUNNER);
-    }
-  }, [runners, isRunnersLoading]);
-
-  // Persist runner on change
-  useEffect(() => {
-    if (runnerId) {
-      localStorage.setItem(STORAGE_KEY_RUNNER, runnerId);
-    } else {
-      localStorage.removeItem(STORAGE_KEY_RUNNER);
-    }
-  }, [runnerId]);
-
   const submit = useCallback(
     async (
       message: string,
@@ -269,8 +251,8 @@ export function useNewSessionFlow(
             : undefined,
           mcpServerUsages: mcpServerUsages.length > 0 ? mcpServerUsages : undefined,
           skillRefs: skillRefs.length > 0 ? skillRefs : undefined,
-          runnerId: runnerId ?? undefined,
           harness,
+          executionTarget,
         };
 
         const executionFields = {
@@ -280,6 +262,7 @@ export function useNewSessionFlow(
           runtimeEnv: context?.runtimeEnv,
           attachments: context?.attachments,
           interactionMode: context?.interactionMode,
+          workspaceFileRefs: context?.workspaceFileRefs,
         };
 
         let sessionId: string;
@@ -338,11 +321,11 @@ export function useNewSessionFlow(
       isSubmitting,
       org,
       harness,
+      executionTarget,
       validModelId,
       workspace,
       mcpServerUsages,
       skillRefs,
-      runnerId,
       agentRef,
       resolution,
       defaultAgent,
@@ -370,8 +353,6 @@ export function useNewSessionFlow(
     setMcpServerUsages,
     skillRefs,
     setSkillRefs,
-    runnerId,
-    setRunnerId,
     workspace,
     sessionVariables,
     isSubmitting,

package/src/session/useSessionConversation.ts

@@ -83,6 +83,15 @@ export interface SendFollowUpOptions {
    * - `"plan"`: read-only analysis, no file mutations.
    */
   readonly interactionMode?: "agent" | "plan";
+  /**
+   * Workspace-relative file paths the user wants the agent to focus on.
+   *
+   * Lightweight "attention" signals — no upload, no injection. The agent
+   * reads these files directly from the workspace filesystem.
+   *
+   * @see {@link CreateAgentExecutionInput.workspaceFileRefs}
+   */
+  readonly workspaceFileRefs?: string[];
 }
 
 /**
@@ -351,7 +360,7 @@ export function useSessionConversation(
 
         if (needsSessionUpdate) {
           // Fetch the latest session to avoid overwriting fields that were
-          // modified server-side (e.g., LLM-generated subject, sandbox_id)
+          // modified server-side (e.g., LLM-generated subject)
           // since the React state was last loaded.
           const freshSession = await stigmer.session.get(sessionId);
           await updateSession(
@@ -373,6 +382,7 @@ export function useSessionConversation(
           runtimeEnv: options?.runtimeEnv,
           attachments: options?.attachments,
           interactionMode: options?.interactionMode,
+          workspaceFileRefs: options?.workspaceFileRefs,
         });
         setPendingExecutionId(result.executionId);
         refetch();
@@ -478,10 +488,10 @@ function buildUpdateInput(
     org: meta.org,
     agentInstanceId: overrides.agentInstanceId ?? (spec?.agentInstanceId || undefined),
     subject: spec?.subject || undefined,
-    threadId: spec?.threadId || undefined,
-    sandboxId: spec?.sandboxId || undefined,
-    runnerId: spec?.runnerId || undefined,
+    harnessStateId: spec?.harnessStateId || undefined,
     harness: spec?.harness,
+    cursorMode: spec?.cursorMode,
+    executionTarget: spec?.executionTarget,
     metadata:
       spec?.metadata && Object.keys(spec.metadata).length > 0
         ? { ...spec.metadata }

package/src/session/useSessionPageFlow.ts

@@ -9,7 +9,8 @@ import { useWorkspaceEntries, type UseWorkspaceEntriesReturn } from "../workspac
 import { useSessionVariables, type UseSessionVariablesReturn } from "../execution/useSessionVariables";
 import type { SessionComposerSubmitContext } from "../composer";
 import { fromProtoHarness, type HarnessOption } from "../models/harness";
-import { Harness } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import { Harness, ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import { fromProtoExecutionTarget, type ExecutionTargetOption } from "./execution-target";
 import { useSessionConversation, type UseSessionConversationReturn } from "./useSessionConversation";
 import { useAgentRefFromSession } from "./useAgentRefFromSession";
 import { usePersistedModel, type UsePersistedModelReturn } from "./usePersistedModel";
@@ -45,6 +46,15 @@ export interface UseSessionPageFlowReturn {
    */
   readonly harness: HarnessOption;
 
+  /**
+   * Where session activities execute (read-only, derived from session spec).
+   *
+   * `"local"` when the client's embedded runner handles activities,
+   * `"cloud"` when the server provisions a sandbox, or `undefined`
+   * when the server decides (UNSPECIFIED).
+   */
+  readonly executionTarget: ExecutionTargetOption | undefined;
+
   /** Persisted model selection: `[modelId, setModelId]`. */
   readonly model: UsePersistedModelReturn;
 
@@ -157,6 +167,9 @@ export function useSessionPageFlow(
   const harness: HarnessOption = fromProtoHarness(
     conv.session?.spec?.harness ?? Harness.UNSPECIFIED,
   );
+  const executionTarget: ExecutionTargetOption | undefined = fromProtoExecutionTarget(
+    conv.session?.spec?.executionTarget ?? ExecutionTarget.UNSPECIFIED,
+  );
   const [persistedModelId, setPersistedModelId] = usePersistedModel({ harness });
 
   const lastExecModelId = useMemo(() => {
@@ -270,6 +283,7 @@ export function useSessionPageFlow(
         runtimeEnv: context?.runtimeEnv,
         attachments: context?.attachments,
         interactionMode: context?.interactionMode,
+        workspaceFileRefs: context?.workspaceFileRefs,
       });
 
       sessionVariables.clear();
@@ -306,6 +320,7 @@ export function useSessionPageFlow(
   return {
     conv,
     harness,
+    executionTarget,
     model,
     agentRef,
     setAgentRef,