@stigmer/react 1.0.3 → 2.0.0

package/src/session/useNewSessionFlow.ts

@@ -10,12 +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"
@@ -38,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}. */
@@ -72,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. */
@@ -91,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
@@ -109,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`.
  *
@@ -137,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}
  * />
@@ -149,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;
@@ -157,13 +168,13 @@ export function useNewSessionFlow(
   });
 
   const { getModel, isLoading: isModelsLoading } = useModelRegistry({ harness });
-  const { runners, isLoading: isRunnersLoading } = useRunnerList(org);
   const { create: createSession } = useCreateSession();
   const { create: createExecution } = useCreateAgentExecution();
   const {
     agent: defaultAgent,
     isLoading: isDefaultAgentLoading,
     error: defaultAgentError,
+    waitForResolution: waitForDefaultAgent,
   } = useDefaultAgent(org);
   const workspace = useWorkspaceEntries();
   const sessionVariables = useSessionVariables();
@@ -173,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);
 
@@ -216,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,
@@ -265,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 = {
@@ -276,6 +262,7 @@ export function useNewSessionFlow(
           runtimeEnv: context?.runtimeEnv,
           attachments: context?.attachments,
           interactionMode: context?.interactionMode,
+          workspaceFileRefs: context?.workspaceFileRefs,
         };
 
         let sessionId: string;
@@ -293,25 +280,29 @@ export function useNewSessionFlow(
             }));
           }
         } else {
-          const defaultInstanceId = defaultAgent?.status?.defaultInstanceId;
-          if (!defaultInstanceId) {
+          let resolvedInstanceId = defaultAgent?.status?.defaultInstanceId;
+          if (!resolvedInstanceId) {
             if (isDefaultAgentLoading) {
+              const resolved = await withTimeout(
+                waitForDefaultAgent(),
+                DEFAULT_AGENT_TIMEOUT_MS,
+                "Default agent did not load in time. Please try again.",
+              );
+              resolvedInstanceId = resolved?.status?.defaultInstanceId;
+            } else if (defaultAgentError) {
               throw new Error(
-                "Loading default agent. Please try again in a moment.",
+                "Failed to load default agent. Please try again.",
               );
             }
-            if (defaultAgentError) {
+            if (!resolvedInstanceId) {
               throw new Error(
-                "Failed to load default agent. Please try again.",
+                "No default agent available. Select an agent to start a session.",
               );
             }
-            throw new Error(
-              "No default agent available. Select an agent to start a session.",
-            );
           }
           ({ sessionId } = await createSession({
             ...sessionFields,
-            agentInstanceId: defaultInstanceId,
+            agentInstanceId: resolvedInstanceId,
           }));
         }
 
@@ -330,16 +321,17 @@ export function useNewSessionFlow(
       isSubmitting,
       org,
       harness,
+      executionTarget,
       validModelId,
       workspace,
       mcpServerUsages,
       skillRefs,
-      runnerId,
       agentRef,
       resolution,
       defaultAgent,
       isDefaultAgentLoading,
       defaultAgentError,
+      waitForDefaultAgent,
       createSession,
       createExecution,
       sessionVariables,
@@ -361,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,

package/src/session/useSessionUsage.ts

@@ -1,21 +1,29 @@
 "use client";
 
-import { useMemo } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
   GetSessionUsageReportInputSchema,
   type GetSessionUsageReportOutput,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
-import type { ModelUsage, RunnerUsageSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import type { ModelUsage, StreamingUsageSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 import { useStigmer } from "../hooks";
+import { isTerminalPhase } from "../execution/execution-phases";
 import { useFetch } from "../internal/useFetch";
 
+/**
+ * Poll cadence for the session usage report while an execution is in flight.
+ * The proxy writes one authoritative billing record per turn, so polling lets
+ * the settled cost climb live during the run rather than only at completion.
+ */
+const ACTIVE_POLL_INTERVAL_MS = 2500;
+
 /**
  * Per-model cost breakdown.
  */
 export interface ModelCostEntry {
-  /** Model identifier (e.g. "claude-sonnet-4-20250514"). */
+  /** Model identifier (e.g. "claude-sonnet-4-6"). */
   readonly model: string;
   /** Provider name (e.g. "anthropic", "openai"). */
   readonly provider: string;
@@ -57,6 +65,12 @@ export interface UseSessionUsageReturn {
   readonly primaryProvider: string;
   /** `true` when usage data is available. */
   readonly hasUsage: boolean;
+  /**
+   * `true` when the displayed cost comes from runner-reported streaming data
+   * rather than settled billing records. The UI should show an "Estimated"
+   * badge when this is true.
+   */
+  readonly isEstimated: boolean;
 }
 
 const EMPTY: UseSessionUsageReturn = {
@@ -71,6 +85,7 @@ const EMPTY: UseSessionUsageReturn = {
   primaryModel: "",
   primaryProvider: "",
   hasUsage: false,
+  isEstimated: false,
 };
 
 function microsToUsd(micros: bigint): number {
@@ -94,27 +109,32 @@ function mapReport(report: GetSessionUsageReportOutput): UseSessionUsageReturn {
   const agg = report.totalUsage;
   if (!agg) return EMPTY;
 
+  const llmCallCount = agg.llmCallCount;
+  const totalTokens = Number(agg.totalTokens);
+  const billableCost = microsToUsd(agg.billableCostMicros);
+
   return {
-    totalCostUsd: microsToUsd(agg.billableCostMicros),
-    totalTokens: Number(agg.totalTokens),
+    totalCostUsd: billableCost,
+    totalTokens,
     inputTokens: Number(agg.inputTokens),
     outputTokens: Number(agg.outputTokens),
     cacheReadTokens: Number(agg.cacheReadInputTokens),
     cacheCreationTokens: Number(agg.cacheCreationInputTokens),
-    llmCallCount: agg.llmCallCount,
+    llmCallCount,
     modelBreakdown: report.modelBreakdown.map(mapModelUsage),
     primaryModel: agg.primaryModel,
     primaryProvider: agg.primaryProvider,
-    hasUsage: true,
+    hasUsage: llmCallCount > 0 || totalTokens > 0 || billableCost > 0,
+    isEstimated: report.isEstimated ?? false,
   };
 }
 
 /**
- * Aggregate runner-reported usage from execution status objects.
+ * Aggregate streaming-reported usage from execution status objects.
  * Used as a fallback when the server-side session usage report is empty
  * (e.g., Cursor harness where the proxy does not capture main agent turns).
  */
-function aggregateRunnerUsage(
+function aggregateStreamingUsage(
   executions: readonly AgentExecution[],
 ): UseSessionUsageReturn {
   let inputTokens = 0;
@@ -127,7 +147,7 @@ function aggregateRunnerUsage(
   let model = "";
 
   for (const exec of executions) {
-    const ru = exec.status?.runnerUsage;
+    const ru = exec.status?.streamingUsage;
     if (!ru || ru.turnCount === 0) continue;
     inputTokens += Number(ru.inputTokens);
     outputTokens += Number(ru.outputTokens);
@@ -166,17 +186,23 @@ function aggregateRunnerUsage(
     primaryModel: model,
     primaryProvider: model ? "cursor" : "",
     hasUsage: true,
+    isEstimated: true,
   };
 }
 
 /**
  * Usage hook for session-level cost and token aggregation.
  *
- * Calls `getSessionUsageReport` to fetch real usage data from the
- * billing domain. Returns zeros while loading or when no session is
- * available.
+ * Uses exactly ONE data source at a time to avoid displaying a cost total
+ * from one pipeline with a model breakdown from another:
+ *
+ * - When billing records exist (proxy-metered), the billing report is shown
+ *   as authoritative (`isEstimated: false`).
+ * - When execution is in-flight and only streaming data is available,
+ *   streaming is shown with `isEstimated: true`.
+ * - The two sources are never mixed in the same display.
  *
- * @param executions - All executions for a session (used to derive session ID).
+ * @param executions - All executions for a session (completed + active).
  */
 export function useSessionUsage(
   executions: readonly AgentExecution[],
@@ -188,28 +214,65 @@ export function useSessionUsage(
     [executions],
   );
 
-  const { data: report } = useFetch(
-    sessionId
-      ? () =>
-          stigmer.agentExecution.getSessionUsageReport(
-            create(GetSessionUsageReportInputSchema, { sessionId }),
-          )
-      : null,
+  // Any execution still in flight means more authoritative records are coming,
+  // so the report must be polled to stay current during the run.
+  const hasActiveExecution = useMemo(
+    () =>
+      executions.some((e) => {
+        const phase = e.status?.phase;
+        return phase !== undefined && !isTerminalPhase(phase);
+      }),
+    [executions],
+  );
+
+  // Stable fetch identity so the poll timer in useFetch is not torn down and
+  // recreated on every streaming re-render (which would prevent it firing).
+  const fetchReport = useCallback(
+    () =>
+      stigmer.agentExecution.getSessionUsageReport(
+        create(GetSessionUsageReportInputSchema, { sessionId: sessionId! }),
+      ),
+    [sessionId, stigmer],
+  );
+
+  const { data: report, refetch } = useFetch(
+    sessionId ? fetchReport : null,
     [sessionId, stigmer],
     null as GetSessionUsageReportOutput | null,
-    { cacheKey: sessionId ? `session-usage:${sessionId}` : undefined },
+    {
+      cacheKey: sessionId ? `session-usage:${sessionId}` : undefined,
+      refetchInterval: hasActiveExecution ? ACTIVE_POLL_INTERVAL_MS : false,
+    },
   );
 
-  const runnerFallback = useMemo(
-    () => aggregateRunnerUsage(executions),
+  // When the last execution settles, poll stops — do one final fetch so the
+  // authoritative total (incl. the final turn) replaces the live estimate
+  // promptly instead of waiting for a remount.
+  const wasActiveRef = useRef(hasActiveExecution);
+  useEffect(() => {
+    if (wasActiveRef.current && !hasActiveExecution) {
+      refetch();
+    }
+    wasActiveRef.current = hasActiveExecution;
+  }, [hasActiveExecution, refetch]);
+
+  const streamingFallback = useMemo(
+    () => aggregateStreamingUsage(executions),
     [executions],
   );
 
   return useMemo(() => {
-    if (report) {
-      const mapped = mapReport(report);
-      if (mapped.hasUsage) return mapped;
-    }
-    return runnerFallback;
-  }, [report, runnerFallback]);
+    const billingReport = report ? mapReport(report) : EMPTY;
+
+    // Authoritative proxy-metered report wins as soon as any record exists.
+    // While an execution runs, per-turn records land continuously and polling
+    // keeps this total fresh, so it is never shadowed by a stale snapshot.
+    if (billingReport.hasUsage) return billingReport;
+
+    // No billing record yet (e.g. before the first turn settles) — fall back
+    // to the runner's display-only streaming estimate.
+    if (streamingFallback.hasUsage) return streamingFallback;
+
+    return EMPTY;
+  }, [report, streamingFallback]);
 }

package/src/skill/SkillDetailView.tsx

@@ -12,6 +12,7 @@ import { useSkill } from "./useSkill";
 import { SkillFileBrowser } from "./SkillFileBrowser";
 import { ErrorMessage } from "../error/ErrorMessage";
 import { VisibilityToggle } from "../library/VisibilityToggle";
+import { PermissionGate } from "../iam-policy/PermissionGate";
 import { MARKDOWN_COMPONENTS, REMARK_PLUGINS, stripFrontmatter } from "../internal/markdown-components";
 import { ResourceDetailShell } from "../resource-detail/ResourceDetailShell";
 import { Section } from "../resource-detail/Section";
@@ -242,20 +243,28 @@ export function SkillDetailView({
     statusLabel: status ? skillStateLabel(status.state) : undefined,
   };
 
-  const isPublic = meta?.visibility === ApiResourceVisibility.visibility_public;
-  const visibilityControl =
-    onVisibilityChange && meta ? (
-      <VisibilityToggle
-        visibility={meta.visibility}
-        onVisibilityChange={onVisibilityChange}
-        isPending={isVisibilityPending}
-      />
-    ) : isPublic ? (
+  const visibilityBadge =
+    meta?.visibility === ApiResourceVisibility.visibility_public ? (
       <span className="shrink-0 rounded-full bg-muted px-2 py-0.5 text-[10px] font-medium text-muted-foreground">
         Public
       </span>
     ) : undefined;
 
+  const visibilityControl =
+    onVisibilityChange && meta ? (
+      <PermissionGate
+        resource={{ kind: "skill", id: meta.id }}
+        relation="can_edit"
+        fallback={visibilityBadge}
+      >
+        <VisibilityToggle
+          visibility={meta.visibility}
+          onVisibilityChange={onVisibilityChange}
+          isPending={isVisibilityPending}
+        />
+      </PermissionGate>
+    ) : visibilityBadge;
+
   let tabContent: React.ReactNode;
   if (activeAdditionalTab) {
     tabContent = activeAdditionalTab.content;