@stigmer/react 3.12.4 → 3.12.6

package/src/identity-account/__tests__/AccountPreferencesPanel.test.tsx

@@ -0,0 +1,267 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  IdentityAccountSchema,
+  type IdentityAccount,
+} from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import type { IdentityAccountInput } from "@stigmer/sdk";
+import type { DeploymentMode } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { DeploymentModeContext } from "../../deployment-mode";
+import { ModelRegistryContext, type ModelRegistryState } from "../../models/ModelRegistryContext";
+import { parseRegistryJson } from "../../models/registry";
+import { AccountPreferencesPanel } from "../AccountPreferencesPanel";
+
+const ACCOUNT: IdentityAccount = create(IdentityAccountSchema, {
+  metadata: { id: "ia-1", name: "Ada Lovelace", slug: "ada", org: "acme" },
+  spec: {
+    idpId: "auth0|abc",
+    email: "ada@acme.example",
+    preferences: { standingContext: "Keep answers terse." },
+  },
+});
+
+const TEST_MODELS = parseRegistryJson({
+  models: [
+    { id: "claude-sonnet-4.6", displayName: "Claude Sonnet 4.6", shortDescription: "", speedTier: "fast", provider: "anthropic", harness: "native", costTier: "standard", featured: true, pricing: { inputPricePerMillion: 3, outputPricePerMillion: 15, cacheWritePricePerMillion: 3.75, cacheReadPricePerMillion: 0.3 } },
+    { id: "default", displayName: "Cursor Auto", shortDescription: "", speedTier: "fast", provider: "cursor", harness: "cursor", costTier: "standard", featured: true, pricing: { inputPricePerMillion: 1.25, outputPricePerMillion: 6, cacheWritePricePerMillion: 1.25, cacheReadPricePerMillion: 0.25 } },
+  ],
+});
+
+const REGISTRY_STATE: ModelRegistryState = {
+  models: TEST_MODELS,
+  isLoading: false,
+  error: null,
+  refetch: () => {},
+};
+
+function createMockStigmer(overrides?: {
+  whoAmI?: ReturnType<typeof vi.fn>;
+  update?: ReturnType<typeof vi.fn>;
+}) {
+  return {
+    identityAccount: {
+      whoAmI: overrides?.whoAmI ?? vi.fn(async () => ACCOUNT),
+      update: overrides?.update ?? vi.fn(async () => ACCOUNT),
+    },
+  } as never;
+}
+
+function renderPanel(client: unknown, mode: DeploymentMode = "cloud") {
+  return render(
+    <StigmerContext.Provider value={client as never}>
+      <DeploymentModeContext.Provider value={mode}>
+        <ModelRegistryContext.Provider value={REGISTRY_STATE}>
+          <AccountPreferencesPanel />
+        </ModelRegistryContext.Provider>
+      </DeploymentModeContext.Provider>
+    </StigmerContext.Provider>,
+  );
+}
+
+afterEach(cleanup);
+
+/**
+ * Waits until the form has synced from server data (the panel copies the
+ * fetched value into local state in a passive effect, one flush after the
+ * field first renders) — interacting earlier races the sync.
+ */
+async function findSyncedField(value: string) {
+  const field = await screen.findByLabelText("Standing context");
+  await waitFor(() => expect(field).toHaveProperty("value", value));
+  return field;
+}
+
+describe("AccountPreferencesPanel", () => {
+  it("renders the cloud notice in local mode without issuing any RPCs", () => {
+    const whoAmI = vi.fn(async () => ACCOUNT);
+    renderPanel(createMockStigmer({ whoAmI }), "local");
+
+    expect(screen.getByRole("status")).toBeTruthy();
+    expect(screen.queryByLabelText("Standing context")).toBeNull();
+    // The inner form must not mount — no doomed whoAmI against a local server.
+    expect(whoAmI).not.toHaveBeenCalled();
+  });
+
+  it("loads and displays the caller's declared standing context", async () => {
+    renderPanel(createMockStigmer());
+
+    await findSyncedField("Keep answers terse.");
+  });
+
+  it("saves the full mapped input — identity fields survive (wipe-bug guard)", async () => {
+    const update = vi.fn(async (_input: IdentityAccountInput) => ACCOUNT);
+    renderPanel(createMockStigmer({ update }));
+
+    const field = await findSyncedField("Keep answers terse.");
+    fireEvent.change(field, { target: { value: "Prefer bullet points." } });
+    fireEvent.click(screen.getByRole("button", { name: "Save changes" }));
+
+    await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+    const input = update.mock.calls[0]![0];
+
+    expect(input.preferences).toEqual({
+      standingContext: "Prefer bullet points.",
+    });
+    // Fields this form never renders must round-trip untouched.
+    expect(input.idpId).toBe("auth0|abc");
+    expect(input.email).toBe("ada@acme.example");
+    // The update pipeline addresses id-first — the id is REQUIRED here:
+    // identity accounts are org-less, so the org+slug fallback can never
+    // match one (the save-path bug this pin guards against).
+    expect(input.id).toBe("ia-1");
+    expect(input.org).toBe("acme");
+    expect(input.slug).toBe("ada");
+  });
+
+  it("refetches the account after a successful save", async () => {
+    const whoAmI = vi.fn(async () => ACCOUNT);
+    renderPanel(createMockStigmer({ whoAmI }));
+
+    const field = await findSyncedField("Keep answers terse.");
+    fireEvent.change(field, { target: { value: "New context" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save changes" }));
+
+    // Initial load + post-save refetch.
+    await waitFor(() => expect(whoAmI).toHaveBeenCalledTimes(2));
+  });
+
+  it("shows the fetch error with a retry action when whoAmI fails", async () => {
+    const whoAmI = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    renderPanel(createMockStigmer({ whoAmI }));
+
+    expect(await screen.findByRole("alert")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Retry" })).toBeTruthy();
+  });
+
+  describe("execution defaults (oss#293 Phase 1.5)", () => {
+    const ACCOUNT_WITH_DEFAULTS: IdentityAccount = create(IdentityAccountSchema, {
+      metadata: { id: "ia-1", name: "Ada Lovelace", slug: "ada", org: "acme" },
+      spec: {
+        idpId: "auth0|abc",
+        email: "ada@acme.example",
+        preferences: {
+          standingContext: "Keep answers terse.",
+          defaultHarness: "cursor",
+          defaultNativeModel: "claude-sonnet-4.6",
+          defaultCursorModel: "default",
+        },
+      },
+    });
+
+    it("renders the harness option rows and registry-fed model selects", async () => {
+      renderPanel(createMockStigmer());
+      await findSyncedField("Keep answers terse.");
+
+      expect(screen.getByRole("radio", { name: "Platform default" })).toBeTruthy();
+      expect(screen.getByRole("radio", { name: "Stigmer" })).toBeTruthy();
+      expect(screen.getByRole("radio", { name: "Cursor" })).toBeTruthy();
+      expect(screen.getByLabelText("Default model — Stigmer")).toBeTruthy();
+      expect(screen.getByLabelText("Default model — Cursor")).toBeTruthy();
+    });
+
+    it("pairs each harness row with its description (the row IS the context)", async () => {
+      renderPanel(createMockStigmer());
+      await findSyncedField("Keep answers terse.");
+
+      // Row subtitles come from HARNESS_META — the single source of harness
+      // display copy — plus the platform-default explainer.
+      expect(screen.getByText("Stigmer picks the harness for new sessions.")).toBeTruthy();
+      expect(screen.getByText("Stigmer's native agent runtime")).toBeTruthy();
+      expect(screen.getByText("Cursor IDE agent with codebase indexing")).toBeTruthy();
+      // The radios' accessible descriptions are wired via aria-describedby.
+      expect(
+        screen.getByRole("radio", { name: "Stigmer" }).getAttribute("aria-describedby"),
+      ).toBeTruthy();
+    });
+
+    it("keeps the non-selected harness's model select editable (per-harness models are independent of the default harness)", async () => {
+      renderPanel(createMockStigmer({ whoAmI: vi.fn(async () => ACCOUNT_WITH_DEFAULTS) }));
+      await findSyncedField("Keep answers terse.");
+
+      // Default harness is cursor, yet the Stigmer model stays settable:
+      // the launcher applies the model of the session's ACTIVE harness, so
+      // hiding or disabling it would remove a real capability.
+      await waitFor(() => {
+        expect(screen.getByRole("radio", { name: "Cursor" })).toHaveProperty("checked", true);
+      });
+      const nativeSelect = screen.getByLabelText("Default model — Stigmer") as HTMLSelectElement;
+      expect(nativeSelect.disabled).toBe(false);
+      fireEvent.change(nativeSelect, { target: { value: "claude-sonnet-4.6" } });
+      expect(nativeSelect.value).toBe("claude-sonnet-4.6");
+    });
+
+    it("reflects the saved defaults in the form", async () => {
+      renderPanel(createMockStigmer({ whoAmI: vi.fn(async () => ACCOUNT_WITH_DEFAULTS) }));
+      await findSyncedField("Keep answers terse.");
+
+      await waitFor(() => {
+        expect(screen.getByRole("radio", { name: "Cursor" })).toHaveProperty("checked", true);
+        expect(screen.getByLabelText("Default model — Stigmer")).toHaveProperty("value", "claude-sonnet-4.6");
+        expect(screen.getByLabelText("Default model — Cursor")).toHaveProperty("value", "default");
+      });
+    });
+
+    it("saves the complete preferences object — all default fields in one write", async () => {
+      const update = vi.fn(async (_input: IdentityAccountInput) => ACCOUNT);
+      renderPanel(createMockStigmer({ update }));
+      await findSyncedField("Keep answers terse.");
+
+      fireEvent.click(screen.getByRole("radio", { name: "Cursor" }));
+      fireEvent.change(screen.getByLabelText("Default model — Stigmer"), {
+        target: { value: "claude-sonnet-4.6" },
+      });
+      fireEvent.click(screen.getByRole("button", { name: "Save changes" }));
+
+      await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+      expect(update.mock.calls[0]![0].preferences).toEqual({
+        standingContext: "Keep answers terse.",
+        defaultHarness: "cursor",
+        defaultNativeModel: "claude-sonnet-4.6",
+        defaultCursorModel: undefined,
+      });
+    });
+
+    it("editing only standing context preserves the structured defaults (nested wipe-bug guard)", async () => {
+      const update = vi.fn(async (_input: IdentityAccountInput) => ACCOUNT_WITH_DEFAULTS);
+      renderPanel(
+        createMockStigmer({ whoAmI: vi.fn(async () => ACCOUNT_WITH_DEFAULTS), update }),
+      );
+
+      const field = await findSyncedField("Keep answers terse.");
+      fireEvent.change(field, { target: { value: "Terser still." } });
+      fireEvent.click(screen.getByRole("button", { name: "Save changes" }));
+
+      await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+      expect(update.mock.calls[0]![0].preferences).toEqual({
+        standingContext: "Terser still.",
+        defaultHarness: "cursor",
+        defaultNativeModel: "claude-sonnet-4.6",
+        defaultCursorModel: "default",
+      });
+    });
+
+    it("keeps a stale saved model legible as an unavailable option", async () => {
+      const stale = create(IdentityAccountSchema, {
+        metadata: { id: "ia-1", name: "Ada", slug: "ada", org: "acme" },
+        spec: {
+          idpId: "auth0|abc",
+          preferences: { defaultNativeModel: "retired-model" },
+        },
+      });
+      renderPanel(createMockStigmer({ whoAmI: vi.fn(async () => stale) }));
+      await findSyncedField("");
+
+      await waitFor(() => {
+        const select = screen.getByLabelText("Default model — Stigmer") as HTMLSelectElement;
+        expect(select.value).toBe("retired-model");
+        expect(
+          Array.from(select.options).some((o) => o.text === "retired-model (unavailable)"),
+        ).toBe(true);
+      });
+    });
+  });
+});

package/src/identity-account/__tests__/useAccountExecutionDefaults.test.tsx

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  IdentityAccountSchema,
+  type IdentityAccount,
+} from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import type { DeploymentMode } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { DeploymentModeContext } from "../../deployment-mode";
+import { useAccountExecutionDefaults } from "../useAccountExecutionDefaults";
+
+function accountWithPreferences(
+  preferences: Record<string, string>,
+): IdentityAccount {
+  return create(IdentityAccountSchema, {
+    metadata: { id: "ia-1", name: "Ada", slug: "ada", org: "acme" },
+    spec: { idpId: "auth0|abc", preferences },
+  });
+}
+
+function createWrapper(whoAmI: ReturnType<typeof vi.fn>, mode: DeploymentMode = "cloud") {
+  const client = { identityAccount: { whoAmI } } as never;
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client}>
+        <DeploymentModeContext.Provider value={mode}>
+          {children}
+        </DeploymentModeContext.Provider>
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+afterEach(cleanup);
+
+describe("useAccountExecutionDefaults", () => {
+  it("returns undefined in local mode without issuing any RPC", async () => {
+    const whoAmI = vi.fn();
+    const { result } = renderHook(() => useAccountExecutionDefaults(), {
+      wrapper: createWrapper(whoAmI, "local"),
+    });
+
+    // Settle any pending effects before asserting the no-RPC invariant.
+    await waitFor(() => expect(result.current).toBeUndefined());
+    expect(whoAmI).not.toHaveBeenCalled();
+  });
+
+  it("shapes declared defaults for the launcher's accountDefaults prop", async () => {
+    const whoAmI = vi.fn(async () =>
+      accountWithPreferences({
+        defaultHarness: "cursor",
+        defaultNativeModel: "claude-sonnet-4.6",
+        defaultCursorModel: "composer-2.5",
+      }),
+    );
+    const { result } = renderHook(() => useAccountExecutionDefaults(), {
+      wrapper: createWrapper(whoAmI),
+    });
+
+    await waitFor(() =>
+      expect(result.current).toEqual({
+        harness: "cursor",
+        nativeModel: "claude-sonnet-4.6",
+        cursorModel: "composer-2.5",
+      }),
+    );
+  });
+
+  it("returns undefined while loading and when nothing is declared", async () => {
+    const whoAmI = vi.fn(async () =>
+      accountWithPreferences({ standingContext: "Keep answers terse." }),
+    );
+    const { result } = renderHook(() => useAccountExecutionDefaults(), {
+      wrapper: createWrapper(whoAmI),
+    });
+
+    expect(result.current).toBeUndefined();
+    await waitFor(() => expect(whoAmI).toHaveBeenCalled());
+    // standing_context alone declares no execution default.
+    expect(result.current).toBeUndefined();
+  });
+
+  it("treats an unknown persisted harness value as undeclared", async () => {
+    const whoAmI = vi.fn(async () =>
+      accountWithPreferences({
+        defaultHarness: "devin",
+        defaultNativeModel: "claude-sonnet-4.6",
+      }),
+    );
+    const { result } = renderHook(() => useAccountExecutionDefaults(), {
+      wrapper: createWrapper(whoAmI),
+    });
+
+    await waitFor(() =>
+      expect(result.current).toEqual({
+        harness: undefined,
+        nativeModel: "claude-sonnet-4.6",
+        cursorModel: undefined,
+      }),
+    );
+  });
+
+  it("returns undefined on a whoAmI failure — degrades to platform defaults", async () => {
+    const whoAmI = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const { result } = renderHook(() => useAccountExecutionDefaults(), {
+      wrapper: createWrapper(whoAmI),
+    });
+
+    await waitFor(() => expect(whoAmI).toHaveBeenCalled());
+    expect(result.current).toBeUndefined();
+  });
+});

package/src/identity-account/__tests__/useMyIdentityAccount.test.tsx

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  IdentityAccountSchema,
+  type IdentityAccount,
+} from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import type { IdentityAccountInput } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useMyIdentityAccount } from "../useMyIdentityAccount";
+import { useUpdateIdentityAccount } from "../useUpdateIdentityAccount";
+
+const ACCOUNT: IdentityAccount = create(IdentityAccountSchema, {
+  metadata: { id: "ia-1", name: "Ada", slug: "ada", org: "acme" },
+  spec: { preferences: { standingContext: "Keep answers terse." } },
+});
+
+/** Renders the data hook and exposes its state via data attributes. */
+function FetchProbe() {
+  const { account, isLoading, error, refetch } = useMyIdentityAccount();
+  return (
+    <button
+      type="button"
+      data-testid="probe"
+      data-loading={String(isLoading)}
+      data-error={String(error !== null)}
+      data-context={account?.spec?.preferences?.standingContext ?? ""}
+      onClick={refetch}
+    />
+  );
+}
+
+function UpdateProbe({ input }: { input: IdentityAccountInput }) {
+  const { update, isUpdating, error } = useUpdateIdentityAccount();
+  return (
+    <button
+      type="button"
+      data-testid="probe"
+      data-updating={String(isUpdating)}
+      data-error={String(error !== null)}
+      onClick={() => void update(input).catch(() => undefined)}
+    />
+  );
+}
+
+function withClient(client: unknown, ui: React.ReactNode) {
+  return render(
+    <StigmerContext.Provider value={client as never}>
+      {ui}
+    </StigmerContext.Provider>,
+  );
+}
+
+afterEach(cleanup);
+
+describe("useMyIdentityAccount", () => {
+  it("fetches the caller's account via whoAmI and supports refetch", async () => {
+    const whoAmI = vi.fn(async () => ACCOUNT);
+    withClient({ identityAccount: { whoAmI } }, <FetchProbe />);
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-context")).toBe(
+        "Keep answers terse.",
+      ),
+    );
+    expect(whoAmI).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(screen.getByTestId("probe"));
+    await waitFor(() => expect(whoAmI).toHaveBeenCalledTimes(2));
+  });
+
+  it("surfaces errors as state", async () => {
+    const whoAmI = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    withClient({ identityAccount: { whoAmI } }, <FetchProbe />);
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-error")).toBe(
+        "true",
+      ),
+    );
+  });
+});
+
+describe("useUpdateIdentityAccount", () => {
+  it("submits the input through identityAccount.update", async () => {
+    const update = vi.fn(async (_input: IdentityAccountInput) => ACCOUNT);
+    const input: IdentityAccountInput = {
+      name: "Ada",
+      org: "acme",
+      slug: "ada",
+      idpId: "auth0|abc",
+      preferences: { standingContext: "New" },
+    };
+    withClient({ identityAccount: { update } }, <UpdateProbe input={input} />);
+
+    fireEvent.click(screen.getByTestId("probe"));
+
+    await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+    expect(update.mock.calls[0]![0]).toEqual(input);
+  });
+
+  it("captures update failures in error state", async () => {
+    const update = vi.fn(async () => {
+      throw new Error("denied");
+    });
+    withClient(
+      { identityAccount: { update } },
+      <UpdateProbe input={{ name: "Ada", org: "acme", idpId: "x" }} />,
+    );
+
+    fireEvent.click(screen.getByTestId("probe"));
+
+    await waitFor(() =>
+      expect(screen.getByTestId("probe").getAttribute("data-error")).toBe(
+        "true",
+      ),
+    );
+  });
+});

package/src/identity-account/index.ts

@@ -3,3 +3,14 @@ export {
   type IdentityAccountGateState,
   type UseIdentityAccountGateReturn,
 } from "./useIdentityAccountGate.js";
+export { useMyIdentityAccount } from "./useMyIdentityAccount.js";
+export type {
+  UseMyIdentityAccountOptions,
+  UseMyIdentityAccountReturn,
+} from "./useMyIdentityAccount.js";
+export { useAccountExecutionDefaults } from "./useAccountExecutionDefaults.js";
+export type { AccountExecutionDefaults } from "./useAccountExecutionDefaults.js";
+export { useUpdateIdentityAccount } from "./useUpdateIdentityAccount.js";
+export type { UseUpdateIdentityAccountReturn } from "./useUpdateIdentityAccount.js";
+export { AccountPreferencesPanel } from "./AccountPreferencesPanel.js";
+export type { AccountPreferencesPanelProps } from "./AccountPreferencesPanel.js";

package/src/identity-account/useAccountExecutionDefaults.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useMemo } from "react";
+import { useMyIdentityAccount } from "./useMyIdentityAccount.js";
+import { useResourceAvailable, ApiResourceKind } from "../deployment-mode.js";
+import type { HarnessOption } from "../models/harness.js";
+
+/**
+ * The current user's account-level execution defaults, shaped for the
+ * session launcher's `accountDefaults` prop.
+ */
+export interface AccountExecutionDefaults {
+  /** Preferred harness for new sessions, when declared. */
+  readonly harness?: HarnessOption;
+  /** Preferred model for native-harness sessions, when declared. */
+  readonly nativeModel?: string;
+  /** Preferred model for cursor-harness sessions, when declared. */
+  readonly cursorModel?: string;
+}
+
+/**
+ * Data hook that reads the current user's execution defaults
+ * (`IdentityAccountSpec.preferences.default_*`) for seeding new-session
+ * composers.
+ *
+ * Returns `undefined` in local mode (no IdentityAccount), while loading,
+ * on error, and when no default is declared — every one of those cases
+ * degrades to the platform's existing defaults, so consumers wire the
+ * result straight through:
+ *
+ * @example
+ * ```tsx
+ * <NewSessionViewer org={org} accountDefaults={useAccountExecutionDefaults()} />
+ * ```
+ *
+ * The defaults are a SEED, not an override: an explicit device-local pick
+ * outranks them (the layered precedence in `useNewSessionFlow`), and the
+ * chosen values ride the execution spec explicitly. Rides
+ * `useMyIdentityAccount`'s cross-mount cache, so the seed is available
+ * synchronously on every visit after the first.
+ */
+export function useAccountExecutionDefaults(): AccountExecutionDefaults | undefined {
+  const available = useResourceAvailable(ApiResourceKind.identity_account);
+  const { account } = useMyIdentityAccount({ enabled: available });
+
+  return useMemo(() => {
+    const prefs = account?.spec?.preferences;
+    if (!prefs) return undefined;
+
+    // The proto validates default_harness to the shipped set, but a client
+    // must not trust persisted data it did not write — unknown values are
+    // treated as undeclared.
+    const harness =
+      prefs.defaultHarness === "native" || prefs.defaultHarness === "cursor"
+        ? (prefs.defaultHarness satisfies HarnessOption)
+        : undefined;
+    const nativeModel = prefs.defaultNativeModel || undefined;
+    const cursorModel = prefs.defaultCursorModel || undefined;
+
+    if (!harness && !nativeModel && !cursorModel) return undefined;
+    return { harness, nativeModel, cursorModel };
+  }, [account]);
+}

package/src/identity-account/useMyIdentityAccount.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link useMyIdentityAccount}. */
+export interface UseMyIdentityAccountOptions {
+  /**
+   * When `false`, the hook is idle: no RPC is issued and `account` stays
+   * `null`. Lets always-called hooks (React's rules) skip the doomed
+   * whoAmI against a local server — pass
+   * `useResourceAvailable(ApiResourceKind.identity_account)` here.
+   *
+   * @default true
+   */
+  readonly enabled?: boolean;
+}
+
+/** Return value of {@link useMyIdentityAccount}. */
+export interface UseMyIdentityAccountReturn {
+  /** The authenticated user's identity account, or `null` while loading / on error. */
+  readonly account: IdentityAccount | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the account from the server (e.g. after an update). */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the current authenticated user's full
+ * {@link IdentityAccount} via `identityAccount.whoAmI()`.
+ *
+ * Unlike {@link useWhoAmI} (a cached identity lookup for "is this me?"
+ * checks), this hook is a refetchable data source for editors of the
+ * caller's own account — after a mutation, call `refetch()` to re-sync.
+ * `whoAmI()` returns the complete resource, so no follow-up `get()` is
+ * needed.
+ *
+ * Cloud-only by nature: the OSS local server does not implement
+ * IdentityAccount. Gate consumers with
+ * `useResourceAvailable(ApiResourceKind.identity_account)` — either by
+ * conditional mounting or via {@link UseMyIdentityAccountOptions.enabled}.
+ *
+ * Cached across mounts under a {@link FetchCacheProvider} (DD-014): a
+ * revisit renders the previous result immediately and refetches in the
+ * background, so consumers that seed UI from the account (e.g. composer
+ * defaults) settle synchronously after the first visit.
+ *
+ * @example
+ * ```tsx
+ * const { account, refetch } = useMyIdentityAccount();
+ * const standingContext =
+ *   account?.spec?.preferences?.standingContext ?? "";
+ * ```
+ */
+export function useMyIdentityAccount(
+  options?: UseMyIdentityAccountOptions,
+): UseMyIdentityAccountReturn {
+  const stigmer = useStigmer();
+  const enabled = options?.enabled ?? true;
+
+  const { data: account, isLoading, isRefetching, error, refetch } = useFetch(
+    enabled ? () => stigmer.identityAccount.whoAmI() : null,
+    [stigmer, enabled],
+    null as IdentityAccount | null,
+    { cacheKey: enabled ? "identity-account:me" : undefined },
+  );
+
+  return { account, isLoading, isRefetching, error, refetch };
+}