@stigmer/react 3.1.13 → 3.1.15

package/src/button/__tests__/Button.test.tsx

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Button } from "../Button";
+
+afterEach(cleanup);
+
+describe("Button", () => {
+  it("renders a native button with the label and fires onClick", () => {
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Create share</Button>);
+
+    const el = screen.getByRole("button", { name: "Create share" });
+    expect(el.tagName).toBe("BUTTON");
+    el.click();
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("defaults type to button so it never submits an enclosing form", () => {
+    render(<Button>Save</Button>);
+    expect(screen.getByRole("button").getAttribute("type")).toBe("button");
+  });
+
+  it("allows an explicit type override", () => {
+    render(<Button type="submit">Submit</Button>);
+    expect(screen.getByRole("button").getAttribute("type")).toBe("submit");
+  });
+
+  it("applies the variant's token classes", () => {
+    const { rerender } = render(<Button>CTA</Button>);
+    const el = screen.getByRole("button");
+    expect(el.className).toContain("bg-primary");
+
+    rerender(<Button variant="outline">CTA</Button>);
+    expect(el.className).toContain("border-border");
+    expect(el.className).not.toContain("bg-primary");
+
+    rerender(<Button variant="ghost">CTA</Button>);
+    expect(el.className).toContain("hover:bg-accent-hover");
+
+    rerender(<Button variant="destructive">CTA</Button>);
+    expect(el.className).toContain("bg-destructive");
+  });
+
+  it("applies the size classes", () => {
+    const { rerender } = render(<Button size="xs">CTA</Button>);
+    const el = screen.getByRole("button");
+    expect(el.className).toContain("px-2.5");
+
+    rerender(<Button size="sm">CTA</Button>);
+    expect(el.className).toContain("px-3");
+  });
+
+  it("renders a leading icon before the label", () => {
+    render(
+      <Button icon={<svg data-testid="icon" aria-hidden="true" />}>
+        Create instance
+      </Button>,
+    );
+
+    const el = screen.getByRole("button", { name: "Create instance" });
+    expect(el.firstElementChild).toBe(screen.getByTestId("icon"));
+  });
+
+  it("passes native attributes through (disabled, aria-label)", () => {
+    const onClick = vi.fn();
+    render(
+      <Button disabled aria-label="Reset link" onClick={onClick}>
+        Reset
+      </Button>,
+    );
+
+    const el = screen.getByRole("button", { name: "Reset link" });
+    expect(el.hasAttribute("disabled")).toBe(true);
+    el.click();
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it("merges caller classes after the variant classes", () => {
+    render(<Button className="mt-2">CTA</Button>);
+    expect(screen.getByRole("button").className).toContain("mt-2");
+  });
+});

package/src/button/index.ts

@@ -0,0 +1,2 @@
+export { Button } from "./Button.js";
+export type { ButtonProps, ButtonSize, ButtonVariant } from "./Button.js";

package/src/empty-state/EmptyState.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { cn } from "@stigmer/theme";
+import { Button } from "../button/Button.js";
 import { useEmptyState } from "./useEmptyState.js";
 import type { EmptyStateProps } from "./types.js";
 
@@ -71,19 +72,16 @@ export function EmptyState({
       {children
         ? <div className="mt-1">{children}</div>
         : action && (
-          <button
-            type="button"
+          <Button
+            // A retry after an error is a recovery affordance, not the
+            // view's call to action — outline keeps it appropriately quiet.
+            variant={variant === "error" ? "outline" : "primary"}
+            icon={action.icon}
             onClick={action.onClick}
-            className={cn(
-              "mt-1 inline-flex items-center rounded-md px-3 py-1.5 text-xs font-medium",
-              variant === "error"
-                ? "border border-input bg-background text-foreground hover:bg-accent hover:text-accent-foreground"
-                : "bg-primary text-primary-foreground hover:bg-primary-hover",
-              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
-            )}
+            className="mt-1"
           >
             {action.label}
-          </button>
+          </Button>
         )}
     </div>
   );

package/src/empty-state/types.ts

@@ -16,6 +16,8 @@ export interface EmptyStateAction {
   readonly label: string;
   /** Click handler. */
   readonly onClick: () => void;
+  /** Optional leading icon (e.g. a plus glyph on create CTAs). */
+  readonly icon?: ReactNode;
 }
 
 /** Options for the {@link useEmptyState} behavior hook. */

package/src/execution/__tests__/useCreateAgentExecution.test.tsx

@@ -3,6 +3,7 @@ import { renderHook, act } from "@testing-library/react";
 import type { ReactNode } from "react";
 import type { Stigmer } from "@stigmer/sdk";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { Harness, ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
 import { StigmerContext } from "../../context";
 import { useCreateAgentExecution } from "../useCreateAgentExecution";
 
@@ -84,6 +85,97 @@ describe("useCreateAgentExecution — executionConfig mapping", () => {
   });
 });
 
+describe("useCreateAgentExecution — one-call session bootstrap (sessionSpec)", () => {
+  it("converts harness and executionTarget options to proto enums", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Customize the landing page",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          workspaceEntries: [
+            { name: "site", source: { localPath: { path: "/repos/site" } } },
+          ],
+          harness: "native",
+          executionTarget: "local",
+        },
+      });
+    });
+
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionId).toBeUndefined();
+    expect(input.sessionSpec).toMatchObject({
+      agentInstanceId: "ain-1",
+      harness: Harness.NATIVE,
+      executionTarget: ExecutionTarget.LOCAL,
+    });
+    expect(input.sessionSpec.workspaceEntries).toEqual([
+      { name: "site", source: { localPath: { path: "/repos/site" } } },
+    ]);
+  });
+
+  it("leaves harness and executionTarget undefined when not chosen (server decides)", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: { agentInstanceId: "ain-1" },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.harness).toBeUndefined();
+    expect(input.sessionSpec.executionTarget).toBeUndefined();
+  });
+
+  it("returns the server-assigned session id from the bootstrap response", async () => {
+    mockCreate.mockResolvedValueOnce({
+      metadata: { id: "aex-1" },
+      spec: { sessionId: "ses-created" },
+    });
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    let created: { executionId: string; sessionId: string } | undefined;
+    await act(async () => {
+      created = await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: { agentInstanceId: "ain-1" },
+      });
+    });
+
+    expect(created).toEqual({ executionId: "aex-1", sessionId: "ses-created" });
+  });
+
+  it("echoes the input session id on the existing-session path", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    let created: { executionId: string; sessionId: string } | undefined;
+    await act(async () => {
+      created = await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Hello",
+      });
+    });
+
+    expect(created).toEqual({ executionId: "aex-1", sessionId: "ses-1" });
+  });
+});
+
 describe("useCreateAgentExecution — supersede link (edit-and-resubmit)", () => {
   it("maps supersedesExecutionId into the create call", async () => {
     const { result } = renderHook(() => useCreateAgentExecution(), {

package/src/execution/index.ts

@@ -1,7 +1,9 @@
 export { useCreateAgentExecution } from "./useCreateAgentExecution.js";
 export type {
+  BootstrapSessionSpec,
   CreateAgentExecutionInput,
   CreateAgentExecutionResult,
+  SharedAgentExecutionFields,
   UseCreateAgentExecutionReturn,
 } from "./useCreateAgentExecution.js";
 

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,
@@ -985,17 +987,19 @@ export type {
 } from "./invitation/index.js";
 
 // Sharing — shared-agent public profile, the anonymous-visitor chat organism,
-// and the owner-side Share experience (dialog, kebab hook, AgentShare hooks).
+// and the owner-side Share experience (Shares tab list, dialog, AgentShare hooks).
 export {
   useSharedAgentProfile,
   SharedAgentChat,
+  draftFromShare,
   sharingAudienceFromProto,
-  useAgentShare,
+  useAgentShares,
+  useCanCreateAgentShare,
   useSaveAgentShare,
+  useDeleteAgentShare,
   useRotateShareLink,
   ShareAgentDialog,
-  useShareAgent,
-  useCreateExternalShareLink,
+  AgentShareList,
   useShareToolReadiness,
   validateOrigin,
   MAX_ALLOWED_ORIGINS,
@@ -1004,16 +1008,16 @@ export type {
   UseSharedAgentProfileOptions,
   UseSharedAgentProfileReturn,
   SharedAgentChatProps,
+  AgentShareCreateIdentity,
   AgentShareDraft,
   SharingAudience,
-  UseAgentShareReturn,
+  UseAgentSharesReturn,
+  UseCanCreateAgentShareReturn,
   UseSaveAgentShareReturn,
+  UseDeleteAgentShareReturn,
   UseRotateShareLinkReturn,
   ShareAgentDialogProps,
-  UseShareAgentArgs,
-  UseShareAgentReturn,
-  UseCreateExternalShareLinkArgs,
-  UseCreateExternalShareLinkReturn,
+  AgentShareListProps,
   ShareToolReadiness,
 } from "./sharing/index.js";
 
@@ -1177,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,