@stigmer/react 3.1.14 → 3.1.15

package/src/agent-instance/AgentInstanceList.tsx

@@ -5,6 +5,7 @@ import { cn } from "@stigmer/theme";
 import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { useAgentInstances } from "./useAgentInstances.js";
+import { Button } from "../button/Button.js";
 import { useEnvironmentList } from "../environment/useEnvironmentList.js";
 import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl.js";
 import { PermissionGate } from "../iam-policy/PermissionGate.js";
@@ -19,8 +20,19 @@ export interface AgentInstanceListProps {
   readonly agentId: string;
   /** The default instance ID (from agent.status.defaultInstanceId) — filtered out of the list. */
   readonly defaultInstanceId?: string;
-  /** Organization slug (needed for environment resolution and create flow). */
+  /**
+   * The AGENT's organization slug (needed for environment resolution
+   * and the create flow). Not the list scope — that is `viewerOrg`,
+   * which differs from `org` when viewing another org's agent.
+   */
   readonly org: string;
+  /**
+   * The viewer's active organization slug. Scopes the list to this
+   * org's instances of the agent, so a member of several orgs sees
+   * exactly the current org context's instances. Omit to default to
+   * the agent's own org.
+   */
+  readonly viewerOrg?: string;
   /** Called when the user wants to create a new instance. */
   readonly onCreateClick?: () => void;
   /** Called when the user clicks an instance row (opens detail). */
@@ -53,6 +65,7 @@ export function AgentInstanceList({
   agentId,
   defaultInstanceId,
   org,
+  viewerOrg,
   onCreateClick,
   onInstanceClick,
   onStartSessionClick,
@@ -60,7 +73,13 @@ export function AgentInstanceList({
   refreshKey,
   className,
 }: AgentInstanceListProps) {
-  const { instances, isLoading, error, refetch } = useAgentInstances(agentId);
+  // Scope the list to the org whose context the viewer is in; when the
+  // host passes no viewerOrg the scope falls back to the agent's own org
+  // (the same-org owner flow).
+  const { instances, isLoading, error, refetch } = useAgentInstances(
+    agentId,
+    viewerOrg || org,
+  );
   const { environments } = useEnvironmentList(org);
 
   // Refetch when refreshKey changes (signals external mutation like create/delete)
@@ -108,27 +127,21 @@ export function AgentInstanceList({
           {userInstances.length} {userInstances.length === 1 ? "instance" : "instances"}
         </h3>
         {onCreateClick && (
-          <button
-            type="button"
+          <Button
+            variant="outline"
+            size="xs"
+            icon={<PlusIcon />}
             onClick={onCreateClick}
-            className={cn(
-              "inline-flex items-center gap-1 rounded-md px-2.5 py-1",
-              "text-xs font-medium",
-              "border border-border text-foreground",
-              "hover:bg-accent-hover",
-              "focus:outline-none focus:ring-2 focus:ring-ring",
-            )}
           >
-            <PlusIcon />
-            Create
-          </button>
+            Create instance
+          </Button>
         )}
       </div>
 
       <div className="overflow-hidden rounded-lg border border-border">
         <table className="w-full text-sm">
           <thead>
-            <tr className="border-b border-border bg-muted/50">
+            <tr className="border-b border-border bg-muted-subtle">
               <th className="px-4 py-2 text-left font-medium text-muted-foreground">Name</th>
               <th className="px-4 py-2 text-left font-medium text-muted-foreground">Environments</th>
               <th className="px-4 py-2 text-left font-medium text-muted-foreground">Visibility</th>
@@ -289,7 +302,7 @@ function LoadingSkeleton() {
   return (
     <div className="space-y-2 py-4">
       {[1, 2, 3].map((i) => (
-        <div key={i} className="h-12 rounded-md bg-muted/50 animate-pulse" />
+        <div key={i} className="h-12 animate-pulse rounded-md bg-muted-faint" />
       ))}
     </div>
   );

package/src/agent-instance/__tests__/agent-instance-hooks.test.tsx

@@ -200,6 +200,25 @@ describe("useAgentInstances", () => {
     expect(result.current.instances).toHaveLength(2);
     expect(result.current.instances[0]?.metadata?.id).toBe("ain-1");
     expect(mockGetByAgent).toHaveBeenCalledTimes(1);
+    expect(mockGetByAgent).toHaveBeenCalledWith(
+      expect.objectContaining({ agentId: "agent-001", org: "" }),
+    );
+  });
+
+  it("threads the org scope into the request", async () => {
+    // The org scope belongs in the RPC, never client-side filtering: the
+    // server narrows a multi-org member's view to one org's instances.
+    mockGetByAgent.mockResolvedValueOnce({ items: [], totalCount: 0 });
+
+    const { result } = renderHook(
+      () => useAgentInstances("agent-001", "acme"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(mockGetByAgent).toHaveBeenCalledWith(
+      expect.objectContaining({ agentId: "agent-001", org: "acme" }),
+    );
   });
 
   it("does not fetch when agentId is null", async () => {

package/src/agent-instance/useAgentInstances.ts

@@ -21,12 +21,19 @@ export interface UseAgentInstancesReturn {
 }
 
 /**
- * Data hook that fetches all instances for a specific agent.
+ * Data hook that fetches instances for a specific agent.
  *
  * Wraps `stigmer.agentInstance.getByAgent()` with loading and error
  * state management. Used on the Agent detail page "Instances" tab to
  * show environment-bound deployments of the agent blueprint.
  *
+ * Pass `org` to scope the list to one organization's instances — the
+ * org-context view a console tab needs. Permissions alone cannot provide
+ * this scope: a member of several orgs can view all of their orgs'
+ * instances of the agent, so the unscoped list merges them. The server
+ * applies the scope (it only ever narrows the permission-bounded view);
+ * omit `org` for the full permission-bounded list.
+ *
  * Pass `null` as `agentId` to skip fetching (stable no-op).
  *
  * Note: the `getByAgent` RPC returns an `AgentInstanceList` whose
@@ -35,11 +42,12 @@ export interface UseAgentInstancesReturn {
  *
  * @example
  * ```tsx
- * const { instances, isLoading } = useAgentInstances(agent.metadata?.id);
+ * const { instances, isLoading } = useAgentInstances(agent.metadata?.id, viewerOrg);
  * ```
  */
 export function useAgentInstances(
   agentId: string | null | undefined,
+  org?: string,
 ): UseAgentInstancesReturn {
   const stigmer = useStigmer();
 
@@ -48,6 +56,7 @@ export function useAgentInstances(
         const resp = await stigmer.agentInstance.getByAgent(
           create(GetAgentInstancesByAgentRequestSchema, {
             agentId,
+            org: org ?? "",
           }),
         );
         return resp.items ? [...resp.items] : [];
@@ -60,7 +69,7 @@ export function useAgentInstances(
     isRefetching,
     error,
     refetch,
-  } = useFetch<readonly AgentInstance[]>(fetchFn, [agentId, stigmer], []);
+  } = useFetch<readonly AgentInstance[]>(fetchFn, [agentId, org, stigmer], []);
 
   return { instances, isLoading, isRefetching, error, refetch };
 }

package/src/button/Button.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+
+/**
+ * Visual weight of a {@link Button}, from most to least prominent.
+ *
+ * - `primary` — filled call to action (one per view: empty-state CTAs,
+ *   dialog confirms).
+ * - `outline` — bordered pill for secondary actions that share a row
+ *   with content (list-header actions like "Create share").
+ * - `ghost` — borderless, hover-surfaced; for repeated inline actions
+ *   (table row actions) where borders would add noise.
+ * - `destructive` — filled danger action (dialog confirms for deletes).
+ *   For inline destructive row actions prefer `ghost` with destructive
+ *   text styling via `className`.
+ */
+export type ButtonVariant = "primary" | "outline" | "ghost" | "destructive";
+
+/**
+ * Size of a {@link Button}.
+ *
+ * - `xs` — compact pill (list headers, table rows).
+ * - `sm` — standard (empty-state CTAs, dialog actions).
+ */
+export type ButtonSize = "xs" | "sm";
+
+/** Props for {@link Button}. Extends the native button attributes. */
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Visual weight. @default "primary" */
+  readonly variant?: ButtonVariant;
+  /** Size. @default "sm" */
+  readonly size?: ButtonSize;
+  /** Optional leading icon, rendered before the label. */
+  readonly icon?: ReactNode;
+}
+
+// One source of truth for each tier's classes: every mapping below is the
+// established idiom already used across the SDK (list-header pills,
+// EmptyState CTAs, ConfirmDialog actions) — collected here so surfaces
+// can stop hand-rolling drifting copies of the same button.
+const VARIANT_CLASSES: Record<ButtonVariant, string> = {
+  primary: "bg-primary text-primary-foreground hover:bg-primary-hover",
+  outline: "border border-border text-foreground hover:bg-accent-hover",
+  ghost: "text-foreground hover:bg-accent-hover",
+  destructive:
+    "bg-destructive text-destructive-foreground hover:bg-destructive-hover",
+};
+
+const SIZE_CLASSES: Record<ButtonSize, string> = {
+  xs: "px-2.5 py-1 text-xs",
+  sm: "px-3 py-1.5 text-xs",
+};
+
+/**
+ * The SDK's shared button primitive.
+ *
+ * A thin, token-compliant wrapper over the native `<button>`: variants
+ * and sizes cover the console's established action tiers, everything
+ * else (handlers, ARIA, `disabled`, `form`) passes through natively.
+ * `type` defaults to `"button"` so a button inside a form never submits
+ * it accidentally.
+ *
+ * All visual properties flow through `--stgm-*` design tokens (DD-005);
+ * hover states use dedicated hover tokens, never opacity modifiers.
+ *
+ * This is an SDK component (DD-001) — embeddable by platform builders.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="outline" size="xs" icon={<PlusIcon />} onClick={onCreate}>
+ *   Create share
+ * </Button>
+ * ```
+ */
+export function Button({
+  variant = "primary",
+  size = "sm",
+  icon,
+  type = "button",
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
+  return (
+    <button
+      type={type}
+      className={cn(
+        "inline-flex items-center gap-1 rounded-md font-medium transition-colors",
+        "motion-reduce:transition-none",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "disabled:pointer-events-none disabled:opacity-50",
+        SIZE_CLASSES[size],
+        VARIANT_CLASSES[variant],
+        className,
+      )}
+      {...rest}
+    >
+      {icon}
+      {children}
+    </button>
+  );
+}

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";