@stigmer/react 3.1.14 → 3.1.16

package/src/execution/useCreateAgentExecution.ts

@@ -2,17 +2,55 @@
 
 import { useCallback, useState } from "react";
 import type { JsonObject } from "@bufbuild/protobuf";
-import type { AttachmentInput, EnvVarInput } from "@stigmer/sdk";
+import type {
+  AttachmentInput,
+  EnvVarInput,
+  McpServerUsageInput,
+  ResourceRef,
+  WorkspaceEntryInput,
+} from "@stigmer/sdk";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
 import { toProtoInteractionMode } from "../composer/interaction-mode.js";
+import { toProtoHarness, type HarnessOption } from "../models/harness.js";
+import {
+  toProtoExecutionTarget,
+  type ExecutionTargetOption,
+} from "../session/execution-target.js";
 
-/** Input for {@link UseCreateAgentExecutionReturn.create}. */
-export interface CreateAgentExecutionInput {
+/**
+ * Spec for the session the server auto-creates on the one-call bootstrap
+ * path (maps to `AgentExecutionSpec.session_spec` in the proto).
+ *
+ * Carries the session shape — workspace, harness, execution target, MCP
+ * servers, skills — alongside the first message, so starting a session
+ * with a configured workspace is a single API call (stigmer/stigmer#249).
+ *
+ * When `agentInstanceId` is omitted, the server resolves the agent's
+ * default instance from the execution's `agentId` (creating the instance
+ * if missing), or falls back to the platform default agent.
+ */
+export interface BootstrapSessionSpec {
+  /** Agent instance the session runs against. Omit to let the server resolve it. */
+  readonly agentInstanceId?: string;
+  /** Initial conversation subject. Omit for an async LLM-generated title. */
+  readonly subject?: string;
+  /** Workspace source entries to attach to the session. */
+  readonly workspaceEntries?: WorkspaceEntryInput[];
+  /** MCP server configurations to include for tool access. */
+  readonly mcpServerUsages?: McpServerUsageInput[];
+  /** Skill references to enable for executions in this session. */
+  readonly skillRefs?: ResourceRef[];
+  /** Execution harness. Immutable after the first execution runs. */
+  readonly harness?: HarnessOption;
+  /** Where session activities execute. Immutable after the first execution runs. */
+  readonly executionTarget?: ExecutionTargetOption;
+}
+
+/** Fields shared by both variants of {@link CreateAgentExecutionInput}. */
+export interface SharedAgentExecutionFields {
   /** Organization slug that owns the session. */
   readonly org: string;
-  /** Session to create the execution within. */
-  readonly sessionId: string;
   /** User message that initiates the execution. */
   readonly message: string;
   /** Override the default model for this execution. */
@@ -106,11 +144,42 @@ export interface CreateAgentExecutionInput {
   readonly supersedesExecutionId?: string;
 }
 
+/**
+ * Input for {@link UseCreateAgentExecutionReturn.create}. Exactly one
+ * session strategy must be provided:
+ *
+ * - **`sessionId`** — Create the execution within an existing session.
+ * - **`sessionSpec`** — One-call bootstrap: the server creates a session
+ *   from the embedded spec and dispatches this execution in it. The new
+ *   session's ID is returned on {@link CreateAgentExecutionResult.sessionId}.
+ *
+ * Providing both is a type error (and an `INVALID_ARGUMENT` server-side).
+ */
+export type CreateAgentExecutionInput = SharedAgentExecutionFields &
+  (
+    | {
+        /** Session to create the execution within. */
+        readonly sessionId: string;
+        /** @internal Discriminant — excluded when `sessionId` is provided. */
+        readonly sessionSpec?: never;
+      }
+    | {
+        /** Spec for the session to auto-create (one-call bootstrap). */
+        readonly sessionSpec: BootstrapSessionSpec;
+        /** @internal Discriminant — excluded when `sessionSpec` is provided. */
+        readonly sessionId?: never;
+      }
+  );
+
 /** Resolved output of {@link UseCreateAgentExecutionReturn.create}. */
 export interface CreateAgentExecutionResult {
   /** Server-assigned identifier for the newly created execution. */
   readonly executionId: string;
-  /** Session the execution belongs to (echoed from input). */
+  /**
+   * Session the execution belongs to. On the `sessionId` path this echoes
+   * the input; on the `sessionSpec` bootstrap path it is the server-created
+   * session's ID.
+   */
   readonly sessionId: string;
 }
 
@@ -132,9 +201,12 @@ export interface UseCreateAgentExecutionReturn {
  * Behavior hook that wraps `agentExecution.create()` with loading/error
  * state.
  *
- * Maps 1:1 to the AgentExecution aggregate — a single run of an agent
- * within an existing session. Requires a `sessionId`; use
- * {@link useCreateSession} to create the session first.
+ * Maps 1:1 to the AgentExecution aggregate — a single run of an agent.
+ * Two session strategies are supported, mirroring the RPC contract:
+ * pass `sessionId` to execute within an existing session (use
+ * {@link useCreateSession} to create one), or pass `sessionSpec` to
+ * bootstrap a new session (workspace, harness, execution target) and
+ * dispatch the first message in a single call.
  *
  * Supports both secret delivery flows:
  *
@@ -165,6 +237,21 @@ export interface UseCreateAgentExecutionReturn {
  *   },
  * });
  * ```
+ *
+ * @example
+ * ```tsx
+ * // One-call bootstrap: session with a workspace + first message
+ * const { create } = useCreateAgentExecution();
+ * const { sessionId } = await create({
+ *   org: "acme",
+ *   message: "Customize the landing page",
+ *   sessionSpec: {
+ *     agentInstanceId: "ain_abc",
+ *     workspaceEntries: [{ name: "site", source: { localPath: { path: "/repos/site" } } }],
+ *     executionTarget: "local",
+ *   },
+ * });
+ * ```
  */
 export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
   const stigmer = useStigmer();
@@ -199,10 +286,27 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
             }
           : undefined;
 
+        const sessionSpec = input.sessionSpec
+          ? {
+              agentInstanceId: input.sessionSpec.agentInstanceId,
+              subject: input.sessionSpec.subject,
+              workspaceEntries: input.sessionSpec.workspaceEntries,
+              mcpServerUsages: input.sessionSpec.mcpServerUsages,
+              skillRefs: input.sessionSpec.skillRefs,
+              harness: input.sessionSpec.harness
+                ? toProtoHarness(input.sessionSpec.harness)
+                : undefined,
+              executionTarget: input.sessionSpec.executionTarget
+                ? toProtoExecutionTarget(input.sessionSpec.executionTarget)
+                : undefined,
+            }
+          : undefined;
+
         const execution = await stigmer.agentExecution.create({
           name: `execution-${Date.now()}`,
           org: input.org,
           sessionId: input.sessionId,
+          sessionSpec,
           agentId: input.agentId,
           message: input.message,
           executionConfig,
@@ -215,7 +319,9 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
 
         return {
           executionId: execution.metadata!.id,
-          sessionId: input.sessionId,
+          // On the bootstrap path the server assigns the session; trust the
+          // response first so both variants report the real session.
+          sessionId: execution.spec?.sessionId ?? input.sessionId ?? "",
         };
       } catch (err) {
         setError(toError(err));

package/src/index.ts

@@ -336,8 +336,10 @@ export {
   getArtifactRenderMode,
 } from "./execution/index.js";
 export type {
+  BootstrapSessionSpec,
   CreateAgentExecutionInput,
   CreateAgentExecutionResult,
+  SharedAgentExecutionFields,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
   UseAgentExecutionActionsOptions,
@@ -1179,6 +1181,10 @@ export type { TabsProps, TabItem } from "./tabs/index.js";
 export { Switch } from "./switch/index.js";
 export type { SwitchProps } from "./switch/index.js";
 
+// Button — shared action primitive (variants for the console's action tiers)
+export { Button } from "./button/index.js";
+export type { ButtonProps, ButtonSize, ButtonVariant } from "./button/index.js";
+
 // Resource Detail — headless hooks, action bar, and composed shell for resource detail pages
 export {
   useCopyResource,

package/src/session/__tests__/useNewSessionFlow.test.tsx

@@ -7,16 +7,9 @@ import type { ModelRegistryState } from "../../models/ModelRegistryContext";
 import { ExecutionTargetContext } from "../../execution-target-context";
 import { RunnerAdapterContext } from "../../runner-adapter";
 import type { RunnerAdapter } from "../../runner-adapter";
-import type { UseCreateSessionReturn } from "../useCreateSession";
-
-const mockCreateSession = vi.fn<UseCreateSessionReturn["create"]>();
-vi.mock("../useCreateSession", () => ({
-  useCreateSession: () => ({
-    create: mockCreateSession,
-    isCreating: false,
-    error: null,
-    clearError: vi.fn(),
-  }),
+const mockGetByReference = vi.fn();
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({ agent: { getByReference: mockGetByReference } }),
 }));
 
 const mockCreateExecution = vi.fn();
@@ -127,8 +120,10 @@ describe("useNewSessionFlow", () => {
     };
     mockDefaultAgent.isLoading = false;
     mockDefaultAgent.error = null;
-    mockCreateSession.mockResolvedValue({ sessionId: "sess-new" });
-    mockCreateExecution.mockResolvedValue({});
+    mockCreateExecution.mockResolvedValue({
+      executionId: "exec-new",
+      sessionId: "sess-new",
+    });
   });
 
   afterEach(() => {
@@ -296,8 +291,8 @@ describe("useNewSessionFlow", () => {
     });
   });
 
-  describe("submit with harness", () => {
-    it("passes harness field to createSession", async () => {
+  describe("submit — one-call bootstrap", () => {
+    it("creates the execution with an embedded sessionSpec in a single call", async () => {
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
 
@@ -305,12 +300,27 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      const sessionInput = mockCreateSession.mock.calls[0][0];
-      expect(sessionInput.harness).toBe("native");
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.message).toBe("Hello");
+      expect(execInput.sessionSpec).toBeDefined();
+      expect(execInput.sessionSpec.agentInstanceId).toBe("default-inst");
+      expect(execInput.sessionId).toBeUndefined();
+    });
+
+    it("passes harness in the sessionSpec", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.harness).toBe("native");
     });
 
-    it("passes cursor harness to createSession after switching", async () => {
+    it("passes cursor harness in the sessionSpec after switching", async () => {
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
 
@@ -320,11 +330,11 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      const sessionInput = mockCreateSession.mock.calls[0][0];
-      expect(sessionInput.harness).toBe("cursor");
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.harness).toBe("cursor");
     });
 
-    it("calls onSessionCreated on success", async () => {
+    it("calls onSessionCreated with the server-assigned session id", async () => {
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
 
@@ -336,7 +346,7 @@ describe("useNewSessionFlow", () => {
     });
 
     it("sets submitError and calls onError on failure", async () => {
-      mockCreateSession.mockRejectedValueOnce(new Error("RPC fail"));
+      mockCreateExecution.mockRejectedValueOnce(new Error("RPC fail"));
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
 
@@ -360,8 +370,48 @@ describe("useNewSessionFlow", () => {
     });
   });
 
+  describe("submit — agent resolution strategies", () => {
+    it("uses the saved resolution's instance directly (no agent lookup)", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      act(() => {
+        result.current.setAgentRef({ org: "acme", slug: "reviewer" });
+        result.current.setResolution({ mode: "saved", instanceId: "saved-inst" });
+      });
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockGetByReference).not.toHaveBeenCalled();
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.agentInstanceId).toBe("saved-inst");
+      expect(execInput.agentId).toBeUndefined();
+    });
+
+    it("resolves a non-saved agentRef to agentId and lets the server pick the instance", async () => {
+      mockGetByReference.mockResolvedValueOnce({ metadata: { id: "agt-resolved" } });
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      act(() => {
+        result.current.setAgentRef({ org: "acme", slug: "reviewer" });
+        result.current.setResolution({ mode: "direct" });
+      });
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockGetByReference).toHaveBeenCalledWith({ org: "acme", slug: "reviewer" });
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.agentId).toBe("agt-resolved");
+      // The server resolves (and if needed creates) the default instance.
+      expect(execInput.sessionSpec.agentInstanceId).toBeUndefined();
+    });
+  });
+
   describe("submit with executionTarget", () => {
-    it("passes executionTarget to createSession when provided", async () => {
+    it("passes executionTarget in the sessionSpec when provided", async () => {
       const opts = { ...defaultOptions(), executionTarget: "local" as const };
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
 
@@ -369,9 +419,9 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      const sessionInput = mockCreateSession.mock.calls[0][0];
-      expect(sessionInput.executionTarget).toBe("local");
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.executionTarget).toBe("local");
     });
 
     it("does not include executionTarget when not provided", async () => {
@@ -382,9 +432,9 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      const sessionInput = mockCreateSession.mock.calls[0][0];
-      expect(sessionInput.executionTarget).toBeUndefined();
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.executionTarget).toBeUndefined();
     });
 
     it("uses context executionTarget when per-hook option is omitted", async () => {
@@ -395,9 +445,9 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      const sessionInput = mockCreateSession.mock.calls[0][0];
-      expect(sessionInput.executionTarget).toBe("local");
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.executionTarget).toBe("local");
     });
 
     it("per-hook executionTarget option overrides context", async () => {
@@ -408,14 +458,14 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      const sessionInput = mockCreateSession.mock.calls[0][0];
-      expect(sessionInput.executionTarget).toBe("local");
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.sessionSpec.executionTarget).toBe("local");
     });
   });
 
-  describe("submit — local runner worker (eager attach)", () => {
-    it("attaches the worker before creating the first execution", async () => {
+  describe("submit — local runner worker (post-create attach)", () => {
+    it("attaches the worker after the bootstrap create returns the session id", async () => {
       const adapter = createMockAdapter();
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), {
@@ -430,10 +480,12 @@ describe("useNewSessionFlow", () => {
       expect(adapter.onSessionOpened).toHaveBeenCalledWith("sess-new");
       expect(adapter.onSessionClosed).not.toHaveBeenCalled();
 
-      // The worker must be polling before the first execution exists.
+      // The session ID only exists after the one-call create, so the attach
+      // follows it. This is safe: the first activity waits on the session's
+      // task queue for a worker (5-minute ScheduleToStart window).
       const openedOrder = adapter.onSessionOpened.mock.invocationCallOrder[0];
       const execOrder = mockCreateExecution.mock.invocationCallOrder[0];
-      expect(openedOrder).toBeLessThan(execOrder);
+      expect(execOrder).toBeLessThan(openedOrder);
     });
 
     it("does not attach a worker when the target is cloud", async () => {
@@ -450,7 +502,7 @@ describe("useNewSessionFlow", () => {
       expect(adapter.onSessionOpened).not.toHaveBeenCalled();
     });
 
-    it("detaches the worker when the first execution fails (no leak)", async () => {
+    it("never attaches a worker when the bootstrap create fails (no leak)", async () => {
       const adapter = createMockAdapter();
       mockCreateExecution.mockRejectedValueOnce(new Error("execution boom"));
       const opts = defaultOptions();
@@ -462,11 +514,30 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(adapter.onSessionOpened).toHaveBeenCalledWith("sess-new");
-      expect(adapter.onSessionClosed).toHaveBeenCalledWith("sess-new");
+      // The create failed before a session existed, so there is no worker
+      // to attach — and therefore nothing to compensate/detach.
+      expect(adapter.onSessionOpened).not.toHaveBeenCalled();
+      expect(adapter.onSessionClosed).not.toHaveBeenCalled();
       expect(result.current.submitError).not.toBeNull();
       expect(opts.onError).toHaveBeenCalled();
     });
+
+    it("surfaces an attach failure without navigating", async () => {
+      const adapter = createMockAdapter();
+      adapter.onSessionOpened.mockRejectedValueOnce(new Error("runner down"));
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), {
+        wrapper: createWrapper("local", adapter),
+      });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(result.current.submitError).not.toBeNull();
+      expect(opts.onError).toHaveBeenCalled();
+      expect(opts.onSessionCreated).not.toHaveBeenCalled();
+    });
   });
 
   describe("host runtime env (getRuntimeEnv)", () => {
@@ -528,7 +599,6 @@ describe("useNewSessionFlow", () => {
       });
 
       // No orphan session, no execution — the failure is fully pre-flight.
-      expect(mockCreateSession).not.toHaveBeenCalled();
       expect(mockCreateExecution).not.toHaveBeenCalled();
       expect(result.current.submitError).toContain("token mint failed");
       expect(opts.onError).toHaveBeenCalled();
@@ -587,7 +657,7 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession.mock.calls[0][0].harness).toBe("cursor");
+      expect(mockCreateExecution.mock.calls[0][0].sessionSpec.harness).toBe("cursor");
     });
   });
 
@@ -607,8 +677,8 @@ describe("useNewSessionFlow", () => {
       });
 
       expect(mockDefaultAgent.waitForResolution).toHaveBeenCalledOnce();
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      expect(mockCreateSession.mock.calls[0][0].agentInstanceId).toBe("awaited-inst");
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      expect(mockCreateExecution.mock.calls[0][0].sessionSpec.agentInstanceId).toBe("awaited-inst");
       expect(opts.onSessionCreated).toHaveBeenCalledWith("sess-new");
       expect(result.current.submitError).toBeNull();
     });
@@ -630,7 +700,7 @@ describe("useNewSessionFlow", () => {
 
       expect(result.current.submitError).toBeTruthy();
       expect(opts.onError).toHaveBeenCalled();
-      expect(mockCreateSession).not.toHaveBeenCalled();
+      expect(mockCreateExecution).not.toHaveBeenCalled();
     });
 
     it("surfaces timeout error when fetch never resolves", async () => {
@@ -661,7 +731,7 @@ describe("useNewSessionFlow", () => {
 
       expect(result.current.submitError).toContain("did not load in time");
       expect(opts.onError).toHaveBeenCalled();
-      expect(mockCreateSession).not.toHaveBeenCalled();
+      expect(mockCreateExecution).not.toHaveBeenCalled();
 
       vi.useRealTimers();
     });
@@ -680,7 +750,7 @@ describe("useNewSessionFlow", () => {
 
       expect(result.current.submitError).toContain("Failed to load default agent");
       expect(opts.onError).toHaveBeenCalled();
-      expect(mockCreateSession).not.toHaveBeenCalled();
+      expect(mockCreateExecution).not.toHaveBeenCalled();
       expect(mockDefaultAgent.waitForResolution).not.toHaveBeenCalled();
     });
   });
@@ -711,8 +781,8 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).toHaveBeenCalledOnce();
-      expect(mockCreateSession.mock.calls[0][0].agentInstanceId).toBe("shared-inst");
+      expect(mockCreateExecution).toHaveBeenCalledOnce();
+      expect(mockCreateExecution.mock.calls[0][0].sessionSpec.agentInstanceId).toBe("shared-inst");
       expect(opts.onSessionCreated).toHaveBeenCalledWith("sess-new");
     });
 
@@ -726,7 +796,6 @@ describe("useNewSessionFlow", () => {
         await result.current.submit("Hello");
       });
 
-      expect(mockCreateSession).not.toHaveBeenCalled();
       expect(mockCreateExecution).not.toHaveBeenCalled();
       expect(result.current.submitError).toContain("still loading");
       expect(opts.onError).toHaveBeenCalled();