@stigmer/react 3.2.2 → 3.3.0

package/src/datastore/useUpdateRecord.ts

@@ -0,0 +1,95 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import {
+  UpdateRecordRequestSchema,
+  type RecordEnvelope,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import type { RecordScope } from "./useRecordList.js";
+
+/** Arguments for a single record update. */
+export interface UpdateRecordArgs extends RecordScope {
+  /** Record id (`dsr_…`). */
+  readonly id: string;
+  /**
+   * Partial merge (DD-005): only the supplied fields change; an
+   * explicit `null` clears a field; absent fields keep their stored
+   * values. Constraints evaluate on the merged result. Build this from
+   * per-field edits with `buildUpdateFields`.
+   */
+  readonly fields: JsonObject;
+}
+
+/** Return value of {@link useUpdateRecord}. */
+export interface UseUpdateRecordReturn {
+  /**
+   * Update one record by id. Resolves with the merged envelope. Rejects
+   * — and sets `error` — on denial or constraint violation; the error's
+   * message is the server's relayable text, byte-for-byte.
+   */
+  readonly updateRecord: (args: UpdateRecordArgs) => Promise<RecordEnvelope>;
+  /** `true` while the update is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `datastore.updateRecord()` with loading and
+ * error state.
+ *
+ * The RPC is an honest tri-state partial merge — the hook adds no
+ * merge semantics of its own. A record in another partition is
+ * NOT_FOUND (DD-010: partition scoping is structural).
+ *
+ * @example
+ * ```tsx
+ * const { updateRecord } = useUpdateRecord();
+ * await updateRecord({
+ *   org: "acme",
+ *   datastore: "clinic",
+ *   collection: "bookings",
+ *   id: "dsr_01j9...",
+ *   fields: { patient_phone: "+15550100", notes: null }, // notes cleared
+ * });
+ * ```
+ */
+export function useUpdateRecord(): UseUpdateRecordReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const updateRecord = useCallback(
+    async (args: UpdateRecordArgs): Promise<RecordEnvelope> => {
+      setIsUpdating(true);
+      setError(null);
+      try {
+        return await stigmer.datastore.updateRecord(
+          create(UpdateRecordRequestSchema, {
+            org: args.org,
+            datastore: args.datastore,
+            collection: args.collection,
+            partition: args.partition ?? "",
+            id: args.id,
+            fields: args.fields,
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { updateRecord, isUpdating, error, clearError };
+}

package/src/environment/EnvironmentListPanel.tsx

@@ -6,6 +6,7 @@ import { getUserMessage } from "@stigmer/sdk";
 import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl.js";
+import { EditResourceYamlDialog } from "../manifest/EditResourceYamlDialog.js";
 import { useEnvironmentList } from "./useEnvironmentList.js";
 import { EnvironmentVariableEditor } from "./EnvironmentVariableEditor.js";
 import { isShareRestrictedEnvironment } from "./shareRestriction.js";
@@ -94,6 +95,7 @@ export function EnvironmentListPanel({
     labels,
   );
   const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [yamlEnvironment, setYamlEnvironment] = useState<Environment | null>(null);
 
   if (onRefetchRef) {
     onRefetchRef(refetch);
@@ -179,9 +181,18 @@ export function EnvironmentListPanel({
             onToggle={() => handleToggle(env)}
             readOnly={readOnly}
             onVisibilityChanged={refetch}
+            onEditYaml={() => setYamlEnvironment(env)}
           />
         );
       })}
+      <EditResourceYamlDialog
+        open={yamlEnvironment !== null}
+        onOpenChange={(open) => {
+          if (!open) setYamlEnvironment(null);
+        }}
+        resource={yamlEnvironment}
+        onApplied={refetch}
+      />
     </div>
   );
 }
@@ -196,12 +207,14 @@ function EnvironmentCard({
   onToggle,
   readOnly,
   onVisibilityChanged,
+  onEditYaml,
 }: {
   environment: Environment;
   isExpanded: boolean;
   onToggle: () => void;
   readOnly: boolean;
   onVisibilityChanged: () => void;
+  onEditYaml: () => void;
 }) {
   const name =
     environment.metadata?.name || environment.metadata?.slug || "Unnamed";
@@ -249,6 +262,17 @@ function EnvironmentCard({
           </div>
         </button>
 
+        {!readOnly && (
+          <button
+            type="button"
+            onClick={onEditYaml}
+            aria-label={`Edit ${name} as YAML`}
+            className="shrink-0 rounded px-1.5 py-0.5 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            Edit YAML
+          </button>
+        )}
+
         {showVisibilityControl && (
           <ResourceVisibilityControl
             kind="environment"

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

@@ -119,12 +119,20 @@ describe("useArtifactInspection — detection + apply", () => {
 
   it("applies a detected Agent and fires onApplied with the result", async () => {
     const getArtifactContent = vi.fn().mockResolvedValue(contentResult(AGENT_YAML));
+    // The apply path routes through the kind-agnostic manifest engine:
+    // the hook parses the YAML into a ManifestDocument and hands it to
+    // stigmer.manifest.apply.
     const apply = vi.fn().mockResolvedValue({
-      metadata: { name: "my-agent", org: "acme", slug: "my-agent" },
+      yamlKind: "Agent",
+      displayName: "Agent",
+      name: "my-agent",
+      org: "acme",
+      slug: "my-agent",
+      id: "agt_01",
     });
     const stigmer = {
       agentExecution: { getArtifactContent },
-      agent: { apply },
+      manifest: { apply },
     } as unknown as Stigmer;
     const onApplied = vi.fn();
 
@@ -144,6 +152,8 @@ describe("useArtifactInspection — detection + apply", () => {
 
     expect(apply).toHaveBeenCalledTimes(1);
     expect(apply.mock.calls[0][0].name).toBe("my-agent");
+    expect(apply.mock.calls[0][0].handler.yamlKind).toBe("Agent");
+    expect(apply.mock.calls[0][0].org).toBe("acme");
     await waitFor(() => expect(result.current.applyResult?.kind).toBe("Agent"));
     expect(onApplied).toHaveBeenCalledTimes(1);
     expect(onApplied.mock.calls[0][0].name).toBe("my-agent");

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

@@ -200,3 +200,128 @@ describe("useLiveAgentExecution", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// The { live } visibility gate (T07)
+// ---------------------------------------------------------------------------
+
+describe("useLiveAgentExecution { live }", () => {
+  it("live: false fetches the snapshot but never subscribes", async () => {
+    const running = executionFixture("aex_p1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result } = renderHook(() =>
+      useLiveAgentExecution("aex_p1", { live: false }),
+    );
+    await waitFor(() => expect(result.current.execution).toBe(running));
+
+    // Non-terminal + fetched, yet the gate stays closed on every render.
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+
+  it("live: true (and omitted) behave identically for a non-terminal execution", async () => {
+    const running = executionFixture("aex_p2", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result } = renderHook(() =>
+      useLiveAgentExecution("aex_p2", { live: true }),
+    );
+    await waitFor(() => expect(result.current.execution).not.toBeNull());
+
+    const lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBe("aex_p2");
+  });
+
+  it("a terminal execution never streams regardless of live", async () => {
+    const terminal = executionFixture("aex_p3", ExecutionPhase.EXECUTION_COMPLETED);
+    mockGet(async () => terminal);
+
+    const { result } = renderHook(() =>
+      useLiveAgentExecution("aex_p3", { live: true }),
+    );
+    await waitFor(() => expect(result.current.execution).toBe(terminal));
+
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+
+  it("false → true attaches the stream in place", async () => {
+    const running = executionFixture("aex_p4", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result, rerender } = renderHook(
+      ({ live }: { live: boolean }) =>
+        useLiveAgentExecution("aex_p4", { live }),
+      { initialProps: { live: false } },
+    );
+    await waitFor(() => expect(result.current.execution).toBe(running));
+
+    let lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBeNull();
+
+    rerender({ live: true });
+
+    lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBe("aex_p4");
+  });
+
+  it("never rewinds: a stream pause keeps the last-streamed snapshot, not the mount fetch", async () => {
+    const fetched = executionFixture("aex_p5", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const streamed = executionFixture("aex_p5", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => fetched);
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      execution: streamed,
+      isStreaming: true,
+    });
+
+    const { result, rerender } = renderHook(
+      ({ live }: { live: boolean }) =>
+        useLiveAgentExecution("aex_p5", { live }),
+      { initialProps: { live: true } },
+    );
+    await waitFor(() => expect(result.current.execution).toBe(streamed));
+
+    // Pause: the stream hook resets to its idle shape (execution: null) —
+    // the exact behavior of an unsubscribed useExecutionStream.
+    mockUseExecutionStream.mockReturnValue(idleStream());
+    rerender({ live: false });
+
+    // The freshest streamed snapshot stays visible; the view never rolls
+    // back to the mount-time fetch.
+    expect(result.current.execution).toBe(streamed);
+  });
+
+  it("does not leak the previous execution's snapshot across an id switch", async () => {
+    const first = executionFixture("aex_p6a", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const streamedFirst = executionFixture("aex_p6a", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const second = executionFixture("aex_p6b", ExecutionPhase.EXECUTION_COMPLETED);
+    mockGet(async (id) => (id === "aex_p6a" ? first : second));
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      execution: streamedFirst,
+      isStreaming: true,
+    });
+
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useLiveAgentExecution(id, { live: true }),
+      { initialProps: { id: "aex_p6a" } },
+    );
+    await waitFor(() => expect(result.current.execution).toBe(streamedFirst));
+
+    // Switch executions; the stream resets while the new fetch is in flight.
+    mockUseExecutionStream.mockReturnValue(idleStream());
+    rerender({ id: "aex_p6b" });
+
+    // The retained snapshot is keyed by id — it must NOT bleed into the
+    // new execution's view.
+    expect(result.current.execution).not.toBe(streamedFirst);
+    await waitFor(() => expect(result.current.execution).toBe(second));
+  });
+});

package/src/execution/index.ts

@@ -13,7 +13,10 @@ export { useExecutionStream } from "./useExecutionStream.js";
 export type { UseExecutionStreamReturn } from "./useExecutionStream.js";
 
 export { useLiveAgentExecution } from "./useLiveAgentExecution.js";
-export type { UseLiveAgentExecutionReturn } from "./useLiveAgentExecution.js";
+export type {
+  UseLiveAgentExecutionOptions,
+  UseLiveAgentExecutionReturn,
+} from "./useLiveAgentExecution.js";
 
 export { useAgentExecutionActions } from "./useAgentExecutionActions.js";
 export type {
@@ -291,12 +294,6 @@ export {
   fileChangeTabPath,
 } from "./file-change-document.js";
 
-export {
-  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
-  agentExecutionTabPath,
-  parseAgentExecutionTabPath,
-} from "./agent-execution-document.js";
-
 export { ArtifactContentRenderer } from "./ArtifactContentRenderer.js";
 export type { ArtifactContentRendererProps } from "./ArtifactContentRenderer.js";
 

package/src/execution/useLiveAgentExecution.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { isNotFound } from "@stigmer/sdk";
@@ -9,6 +9,23 @@ import { useFetch } from "../internal/useFetch.js";
 import { isTerminalPhase } from "./execution-phases.js";
 import { useExecutionStream } from "./useExecutionStream.js";
 
+/** Options for {@link useLiveAgentExecution}. */
+export interface UseLiveAgentExecutionOptions {
+  /**
+   * Whether the live stream may be open. Defaults to `true`.
+   *
+   * When `false`, the snapshot fetch still runs (so consumers always have
+   * something to render) but no subscription is opened — the
+   * visibility-gating seam for surfaces that mount many executions at once
+   * (e.g. inline agent-call transcripts in the workflow task thread, where
+   * only on-screen cards stream). A `false → true` transition attaches the
+   * stream in place; a `true → false` transition pauses it while the
+   * last-streamed snapshot stays visible (the view never rewinds to the
+   * mount-time snapshot).
+   */
+  readonly live?: boolean;
+}
+
 /** Return value of {@link useLiveAgentExecution}. */
 export interface UseLiveAgentExecutionReturn {
   /**
@@ -67,8 +84,10 @@ export interface UseLiveAgentExecutionReturn {
  */
 export function useLiveAgentExecution(
   executionId: string | null,
+  options?: UseLiveAgentExecutionOptions,
 ): UseLiveAgentExecutionReturn {
   const stigmer = useStigmer();
+  const live = options?.live ?? true;
 
   const fetchFn = executionId
     ? async () => {
@@ -94,12 +113,31 @@ export function useLiveAgentExecution(
   // snapshot never advances, so a run that terminates mid-stream does not
   // flip this gate and unmount-thrash the subscription — useExecutionStream
   // ends itself on the terminal snapshot (completion is phase-driven).
+  // `live` is the consumer's visibility gate layered on top (an off-screen
+  // surface pauses its subscription without losing the fetch).
   const fetchedPhase =
     fetched?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
-  const shouldStream = fetched !== null && !isTerminalPhase(fetchedPhase);
+  const shouldStream =
+    live && fetched !== null && !isTerminalPhase(fetchedPhase);
   const stream = useExecutionStream(shouldStream ? executionId : null);
 
-  const execution = stream.execution ?? fetched;
+  // Retain the freshest snapshot ever shown for THIS execution across a
+  // stream pause (`live: true → false`): useExecutionStream resets its
+  // store when unsubscribed, so without this a paused surface would rewind
+  // to the mount-time fetch — visibly rolling the view backwards. Keyed by
+  // id so an execution switch never leaks the previous one's snapshot.
+  const lastStreamedRef = useRef<{
+    id: string;
+    execution: AgentExecution;
+  } | null>(null);
+  if (executionId && stream.execution) {
+    lastStreamedRef.current = { id: executionId, execution: stream.execution };
+  } else if (lastStreamedRef.current?.id !== executionId) {
+    lastStreamedRef.current = null;
+  }
+
+  const execution =
+    stream.execution ?? lastStreamedRef.current?.execution ?? fetched;
   const phase =
     execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
 

package/src/iam-policy/__tests__/useCheckPermission.test.tsx

@@ -0,0 +1,221 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { StigmerContext } from "../../context";
+import {
+  useCheckPermission,
+  type CheckPermissionOptions,
+  type PermissionCheckResource,
+} from "../useCheckPermission";
+
+function createMockStigmer(checkMyPermission: ReturnType<typeof vi.fn>) {
+  return { iamPolicy: { checkMyPermission } } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client as never}>
+        {children}
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+/** Renders the hook and exposes its state via data attributes. */
+function Probe({
+  resource,
+  relation = "can_edit",
+  options,
+}: {
+  resource: PermissionCheckResource | null;
+  relation?: string;
+  options?: CheckPermissionOptions;
+}) {
+  const { allowed, isLoading, error } = useCheckPermission(
+    resource,
+    relation,
+    options,
+  );
+  return (
+    <div
+      data-testid="probe"
+      data-allowed={String(allowed)}
+      data-loading={String(isLoading)}
+      data-error={String(error !== null)}
+    />
+  );
+}
+
+const AGENT: PermissionCheckResource = { kind: "agent", id: "agt_1" };
+
+/** A checkMyPermission stub that stays pending until resolved manually. */
+function pendingCheck() {
+  let resolve!: (value: { isAuthorized: boolean }) => void;
+  let reject!: (err: unknown) => void;
+  const check = vi.fn().mockReturnValue(
+    new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    }),
+  );
+  return { check, resolve: (v: boolean) => resolve({ isAuthorized: v }), reject: (e: unknown) => reject(e) };
+}
+
+afterEach(cleanup);
+
+describe("useCheckPermission — fail-open (default)", () => {
+  it("is allowed while the check is in flight", async () => {
+    const { check } = pendingCheck();
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    expect(probe.getAttribute("data-allowed")).toBe("true");
+    await waitFor(() =>
+      expect(probe.getAttribute("data-loading")).toBe("true"),
+    );
+  });
+
+  it("respects an explicit server denial", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: false });
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("false"),
+    );
+  });
+
+  it("respects an explicit server grant", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: true });
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    await waitFor(() => expect(probe.getAttribute("data-loading")).toBe("false"));
+    expect(probe.getAttribute("data-allowed")).toBe("true");
+    expect(probe.getAttribute("data-error")).toBe("false");
+  });
+
+  it("fails open on RPC rejection (OSS single-user mode)", async () => {
+    const check = vi.fn().mockRejectedValue(new Error("unimplemented"));
+    render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    await waitFor(() => expect(probe.getAttribute("data-error")).toBe("true"));
+    expect(probe.getAttribute("data-allowed")).toBe("true");
+    expect(probe.getAttribute("data-loading")).toBe("false");
+  });
+
+  it("is allowed when resource is null (check skipped, no RPC)", () => {
+    const check = vi.fn();
+    render(<Probe resource={null} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true");
+    expect(check).not.toHaveBeenCalled();
+  });
+});
+
+describe("useCheckPermission — fail-closed", () => {
+  const CLOSED: CheckPermissionOptions = { fail: "closed" };
+
+  it("is denied while the check is in flight (no flash of gated UI)", async () => {
+    const { check } = pendingCheck();
+    render(<Probe resource={AGENT} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    expect(probe.getAttribute("data-allowed")).toBe("false");
+    await waitFor(() =>
+      expect(probe.getAttribute("data-loading")).toBe("true"),
+    );
+    expect(probe.getAttribute("data-allowed")).toBe("false");
+  });
+
+  it("is allowed only on an explicit server grant", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: true });
+    render(<Probe resource={AGENT} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+  });
+
+  it("fails closed on RPC rejection", async () => {
+    const check = vi.fn().mockRejectedValue(new Error("unimplemented"));
+    render(<Probe resource={AGENT} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    const probe = screen.getByTestId("probe");
+    await waitFor(() => expect(probe.getAttribute("data-error")).toBe("true"));
+    expect(probe.getAttribute("data-allowed")).toBe("false");
+    expect(probe.getAttribute("data-loading")).toBe("false");
+  });
+
+  it("is denied when resource is null (check skipped)", () => {
+    const check = vi.fn();
+    render(<Probe resource={null} options={CLOSED} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+
+    expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("false");
+    expect(check).not.toHaveBeenCalled();
+  });
+});
+
+describe("useCheckPermission — caching", () => {
+  it("serves repeat checks of the same triple from the mount cache", async () => {
+    const check = vi.fn().mockResolvedValue({ isAuthorized: true });
+    const { rerender } = render(<Probe resource={AGENT} />, {
+      wrapper: wrapper(createMockStigmer(check)),
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+
+    // Switch relation (new triple → one more RPC), then switch back
+    // (cached triple → served without an RPC).
+    rerender(<Probe resource={AGENT} relation="can_delete" />);
+    await waitFor(() => expect(check).toHaveBeenCalledTimes(2));
+    rerender(<Probe resource={AGENT} relation="can_edit" />);
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+    expect(check).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not cache a failed check as a verdict", async () => {
+    // First mount errors; the error must not be pinned as `true` — a
+    // remount (fresh cache) with a healthy server gets the real verdict.
+    const failing = vi.fn().mockRejectedValue(new Error("blip"));
+    const { unmount } = render(
+      <Probe resource={AGENT} options={{ fail: "closed" }} />,
+      { wrapper: wrapper(createMockStigmer(failing)) },
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-error")).toBe("true"),
+    );
+    expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("false");
+    unmount();
+
+    const healthy = vi.fn().mockResolvedValue({ isAuthorized: true });
+    render(<Probe resource={AGENT} options={{ fail: "closed" }} />, {
+      wrapper: wrapper(createMockStigmer(healthy)),
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-allowed")).toBe("true"),
+    );
+  });
+});

package/src/iam-policy/index.ts

@@ -75,6 +75,7 @@ export {
 
 export {
   useCheckPermission,
+  type CheckPermissionOptions,
   type PermissionCheckResource,
   type UseCheckPermissionReturn,
 } from "./useCheckPermission.js";