@stigmer/react 3.1.6 → 3.1.8

package/src/execution/__tests__/write-back-utils.test.ts

@@ -0,0 +1,135 @@
+/**
+ * write-back-utils — the structured seam between the runner's raw
+ * `git diff --stat` text and the presentation layer. The parser must be
+ * strict: wrong numbers are worse than the raw-text fallback, so anything
+ * that is not the exact trailing summary line returns null.
+ */
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { WorkspaceWriteBackSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+import {
+  parseDiffStatSummary,
+  trailingDiffStatLine,
+  writeBackDisplayName,
+} from "../write-back-utils";
+
+describe("parseDiffStatSummary", () => {
+  it("parses the full three-segment summary line", () => {
+    expect(
+      parseDiffStatSummary(" 3 files changed, 42 insertions(+), 7 deletions(-)"),
+    ).toEqual({ filesChanged: 3, insertions: 42, deletions: 7 });
+  });
+
+  it("parses singular forms (1 file / 1 insertion / 1 deletion)", () => {
+    expect(
+      parseDiffStatSummary(" 1 file changed, 1 insertion(+), 1 deletion(-)"),
+    ).toEqual({ filesChanged: 1, insertions: 1, deletions: 1 });
+  });
+
+  it("parses an insertions-only summary (deletions segment omitted by git)", () => {
+    expect(parseDiffStatSummary(" 1 file changed, 55 insertions(+)")).toEqual({
+      filesChanged: 1,
+      insertions: 55,
+      deletions: 0,
+    });
+  });
+
+  it("parses a deletions-only summary (insertions segment omitted by git)", () => {
+    expect(parseDiffStatSummary(" 2 files changed, 9 deletions(-)")).toEqual({
+      filesChanged: 2,
+      insertions: 0,
+      deletions: 9,
+    });
+  });
+
+  it("parses a bare 'N file changed' summary with no count segments", () => {
+    expect(parseDiffStatSummary(" 1 file changed")).toEqual({
+      filesChanged: 1,
+      insertions: 0,
+      deletions: 0,
+    });
+  });
+
+  it("reads the trailing line of a full --stat block, ignoring per-file lines", () => {
+    const stat = [
+      " notes.md                    | 55 ++++++++++",
+      " src/{old.ts => new.ts}      |  5 +-",
+      " 2 files changed, 58 insertions(+), 2 deletions(-)",
+    ].join("\n");
+    expect(parseDiffStatSummary(stat)).toEqual({
+      filesChanged: 2,
+      insertions: 58,
+      deletions: 2,
+    });
+  });
+
+  it("tolerates trailing whitespace/newlines after the summary line", () => {
+    expect(parseDiffStatSummary(" 1 file changed, 2 insertions(+)\n\n")).toEqual({
+      filesChanged: 1,
+      insertions: 2,
+      deletions: 0,
+    });
+  });
+
+  it("returns null for an empty or blank string", () => {
+    expect(parseDiffStatSummary("")).toBeNull();
+    expect(parseDiffStatSummary("  \n  ")).toBeNull();
+  });
+
+  it("returns null for unrecognized text rather than guessing", () => {
+    expect(parseDiffStatSummary(" changed")).toBeNull();
+    expect(parseDiffStatSummary("nothing to see here")).toBeNull();
+    // A per-file line with no trailing summary must not parse.
+    expect(parseDiffStatSummary(" notes.md | 55 +++")).toBeNull();
+  });
+});
+
+describe("trailingDiffStatLine", () => {
+  it("returns the last non-empty line, trimmed", () => {
+    expect(trailingDiffStatLine(" a.ts | 1 +\n 1 file changed \n\n")).toBe(
+      "1 file changed",
+    );
+  });
+
+  it("returns null for blank input", () => {
+    expect(trailingDiffStatLine("")).toBeNull();
+    expect(trailingDiffStatLine(" \n ")).toBeNull();
+  });
+});
+
+describe("writeBackDisplayName", () => {
+  it("prefers the configured workspace entry name", () => {
+    const wb = create(WorkspaceWriteBackSchema, {
+      workspaceEntryName: "acme/api",
+      pullRequestUrl: "https://github.com/other/repo/pull/1",
+    });
+    expect(writeBackDisplayName(wb)).toBe("acme/api");
+  });
+
+  // Single-entry sessions can write back under an empty entry name (the
+  // runner's resolveEntry convention) — the repo identity from the PR URL is
+  // the next-most-honest label.
+  it("derives owner/repo from the PR URL when the entry name is empty", () => {
+    const wb = create(WorkspaceWriteBackSchema, {
+      workspaceEntryName: "",
+      pullRequestUrl: "https://github.com/acme/my-app/pull/42",
+    });
+    expect(writeBackDisplayName(wb)).toBe("acme/my-app");
+  });
+
+  it("falls back to the generic label when neither name nor PR URL exists", () => {
+    const wb = create(WorkspaceWriteBackSchema, {
+      workspaceEntryName: "",
+      pullRequestUrl: "",
+    });
+    expect(writeBackDisplayName(wb)).toBe("Workspace");
+  });
+
+  it("does not mis-parse a non-PR URL", () => {
+    const wb = create(WorkspaceWriteBackSchema, {
+      workspaceEntryName: "",
+      pullRequestUrl: "https://github.com/acme/my-app",
+    });
+    expect(writeBackDisplayName(wb)).toBe("Workspace");
+  });
+});

package/src/execution/index.ts

@@ -80,6 +80,13 @@ export type { UseWorkspaceWriteBacksReturn } from "./useWorkspaceWriteBacks.js";
 export { WriteBackCard } from "./WriteBackCard.js";
 export type { WriteBackCardProps } from "./WriteBackCard.js";
 
+export {
+  parseDiffStatSummary,
+  trailingDiffStatLine,
+  writeBackDisplayName,
+} from "./write-back-utils.js";
+export type { DiffStatSummary } from "./write-back-utils.js";
+
 export { FileChangesView, FileChangeDiff } from "./FileChangesView.js";
 export type { FileChangesViewProps, FileChangeDiffProps } from "./FileChangesView.js";
 

package/src/execution/write-back-utils.ts

@@ -0,0 +1,107 @@
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+
+// ---------------------------------------------------------------------------
+// diff --stat summary parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregate change statistics parsed from a `git diff --stat` summary line.
+ *
+ * @see parseDiffStatSummary
+ */
+export interface DiffStatSummary {
+  /** Number of files with changes. */
+  readonly filesChanged: number;
+  /** Total inserted lines across all files. */
+  readonly insertions: number;
+  /** Total deleted lines across all files. */
+  readonly deletions: number;
+}
+
+/**
+ * The trailing summary line git appends to `--stat` output. All three count
+ * segments are optional-but-ordered in git's formatting; an insertions-only
+ * diff omits the deletions segment entirely (and vice versa).
+ */
+const DIFF_STAT_SUMMARY_RE =
+  /^(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?$/;
+
+/**
+ * Parses the trailing summary line of a `git diff --stat` output into
+ * structured counts.
+ *
+ * `WorkspaceWriteBack.diff_summary` stores the raw `--stat` text (see the
+ * runner's `WriteBackCoordinator.updateStatus`). The per-file lines above the
+ * summary are NOT parseable honestly — git truncates long paths — but the
+ * trailing "N files changed, M insertions(+), K deletions(-)" line is stable
+ * and locale-independent, so it is the one part safe to structure.
+ *
+ * Returns `null` when the text has no recognizable summary line (empty
+ * string, or a format drift), letting callers fall back to rendering the raw
+ * text rather than showing wrong numbers.
+ *
+ * @example
+ * ```ts
+ * parseDiffStatSummary(" notes.md | 55 +++\n 1 file changed, 55 insertions(+)");
+ * // { filesChanged: 1, insertions: 55, deletions: 0 }
+ * ```
+ */
+export function parseDiffStatSummary(
+  diffSummary: string,
+): DiffStatSummary | null {
+  const line = trailingDiffStatLine(diffSummary);
+  if (line === null) return null;
+
+  const match = DIFF_STAT_SUMMARY_RE.exec(line);
+  if (!match) return null;
+
+  return {
+    filesChanged: Number(match[1]),
+    insertions: Number(match[2] ?? 0),
+    deletions: Number(match[3] ?? 0),
+  };
+}
+
+/**
+ * The last non-empty line of a `diff --stat` text — the summary line when the
+ * text is well-formed, and the honest single-line fallback to display when
+ * {@link parseDiffStatSummary} cannot structure it. `null` for blank input.
+ */
+export function trailingDiffStatLine(diffSummary: string): string | null {
+  const lines = diffSummary.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line) return line;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Display name resolution
+// ---------------------------------------------------------------------------
+
+/** Matches `https://github.com/{owner}/{repo}/pull/{n}` (any git host). */
+const PULL_REQUEST_URL_RE = /^https?:\/\/[^/]+\/([^/]+)\/([^/]+)\/pull\/\d+/;
+
+/**
+ * Resolves the human-facing name for a write-back's header.
+ *
+ * A write-back names its workspace entry, but single-entry sessions can
+ * legitimately write back under an EMPTY `workspace_entry_name` — the runner's
+ * `WriteBackCoordinator.resolveEntry` convention, mirrored by
+ * `useWorkspaceReadRefs`. (The Console derives entry names from the git URL,
+ * so this mostly surfaces for CLI/SDK-created sessions.) Rather than render a
+ * blank title, fall back through what the record can still prove:
+ *
+ * 1. `workspace_entry_name` — the configured name, when present.
+ * 2. `owner/repo` parsed from `pull_request_url` — the repository identity.
+ * 3. `"Workspace"` — the honest generic label when neither exists.
+ */
+export function writeBackDisplayName(writeBack: WorkspaceWriteBack): string {
+  if (writeBack.workspaceEntryName) return writeBack.workspaceEntryName;
+
+  const match = PULL_REQUEST_URL_RE.exec(writeBack.pullRequestUrl);
+  if (match) return `${match[1]}/${match[2]}`;
+
+  return "Workspace";
+}

package/src/index.ts

@@ -323,6 +323,9 @@ export {
   execIdFromStorageKey,
   useWorkspaceWriteBacks,
   WriteBackCard,
+  parseDiffStatSummary,
+  trailingDiffStatLine,
+  writeBackDisplayName,
   FileChangesView,
   FileChangeDiff,
   EmptyChangeNotice,
@@ -419,6 +422,7 @@ export type {
   UseFileChangeContentReturn,
   UseWorkspaceWriteBacksReturn,
   WriteBackCardProps,
+  DiffStatSummary,
   FileChangesViewProps,
   FileChangeDiffProps,
   EmptyChangeNoticeProps,
@@ -980,6 +984,32 @@ export type {
   InvitationRedemptionProps,
 } from "./invitation/index.js";
 
+// Sharing — shared-agent public profile, the anonymous-visitor chat organism,
+// and the owner-side Share experience (dialog, kebab hook, sharing mutation).
+export {
+  useSharedAgentProfile,
+  SharedAgentChat,
+  sharingAudienceFromProto,
+  useUpdateAgentSharing,
+  useRotateShareLink,
+  ShareAgentDialog,
+  useShareAgent,
+  validateOrigin,
+  MAX_ALLOWED_ORIGINS,
+} from "./sharing/index.js";
+export type {
+  UseSharedAgentProfileOptions,
+  UseSharedAgentProfileReturn,
+  SharedAgentChatProps,
+  AgentSharingDraft,
+  SharingAudience,
+  UseUpdateAgentSharingReturn,
+  UseRotateShareLinkReturn,
+  ShareAgentDialogProps,
+  UseShareAgentArgs,
+  UseShareAgentReturn,
+} from "./sharing/index.js";
+
 // Error — structured error display with classification, retry, and contextual guidance
 export { ErrorMessage, SecretFlowErrorGuide, isSecretFlowError } from "./error/index.js";
 export type { ErrorMessageProps, SecretFlowErrorGuideProps } from "./error/index.js";
@@ -1136,6 +1166,10 @@ export type {
 export { Tabs } from "./tabs/index.js";
 export type { TabsProps, TabItem } from "./tabs/index.js";
 
+// Switch — accessible on/off toggle primitive (WAI-ARIA Switch pattern)
+export { Switch } from "./switch/index.js";
+export type { SwitchProps } from "./switch/index.js";
+
 // Resource Detail — headless hooks, action bar, and composed shell for resource detail pages
 export {
   useCopyResource,

package/src/internal/dev/__tests__/use-key-stability.test.ts

@@ -15,10 +15,14 @@ describe("useKeyStability", () => {
   let warnSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
+    // Perf logging is opt-in (off by default). Enable it via the browser
+    // runtime flag so these behavioral assertions exercise the warning path.
+    (globalThis as { __STIGMER_PERF__?: boolean }).__STIGMER_PERF__ = true;
     warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
   });
 
   afterEach(() => {
+    delete (globalThis as { __STIGMER_PERF__?: boolean }).__STIGMER_PERF__;
     warnSpy.mockRestore();
   });
 

package/src/internal/dev/__tests__/use-render-tracer.test.ts

@@ -6,10 +6,14 @@ describe("useRenderTracer", () => {
   let debugSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
+    // Perf logging is opt-in (off by default). Enable it via the browser
+    // runtime flag so these behavioral assertions exercise the logging path.
+    (globalThis as { __STIGMER_PERF__?: boolean }).__STIGMER_PERF__ = true;
     debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
   });
 
   afterEach(() => {
+    delete (globalThis as { __STIGMER_PERF__?: boolean }).__STIGMER_PERF__;
     debugSpy.mockRestore();
   });
 

package/src/internal/dev/dom-counter.ts

@@ -1,6 +1,5 @@
 import { type RefObject, useEffect, useRef } from "react";
-
-const DEV = process.env.NODE_ENV !== "production";
+import { isPerfLoggingEnabled } from "./enabled.js";
 
 /** Log the node count every Nth trigger. */
 const LOG_EVERY = 10;
@@ -23,7 +22,7 @@ export function useDomNodeCount(
   const triggerCountRef = useRef(0);
 
   useEffect(() => {
-    if (!DEV) return;
+    if (!isPerfLoggingEnabled()) return;
 
     triggerCountRef.current += 1;
     if (triggerCountRef.current % LOG_EVERY !== 0) return;

package/src/internal/dev/enabled.ts

@@ -0,0 +1,39 @@
+// Master switch for the SDK's dev-only performance instrumentation (the
+// `[stgm:perf:*]` logs emitted by useStreamRate, useRenderTracer, useDomNodeCount,
+// useKeyStability, and DevProfiler).
+//
+// Off by default in every environment. These logs are pure noise for anyone not
+// actively profiling, and in a non-browser TTY consumer — notably the `stigmer`
+// CLI's Ink UI — console output is not filtered by a devtools log level, so it
+// corrupts the rendered terminal. The old `NODE_ENV !== "production"` gate
+// assumed a browser devtools context (where `console.debug` is hidden by
+// default), which does not hold for Node consumers.
+//
+// Opt in without a rebuild:
+//   - Node (CLI, tests):              STIGMER_PERF=1 stigmer run ...
+//   - Browser (web/desktop devtools): globalThis.__STIGMER_PERF__ = true
+//
+// Still hard-gated on non-production so production bundles dead-code-eliminate
+// the instrumentation entirely (bundlers inline `process.env.NODE_ENV`).
+
+/** Reads the Node opt-in env var, guarding environments without `process`. */
+function envFlagEnabled(): boolean {
+  const env = typeof process !== "undefined" ? process.env : undefined;
+  const value = env?.STIGMER_PERF;
+  return value === "1" || value === "true";
+}
+
+/** Reads the browser runtime opt-in (toggle live from devtools). */
+function globalFlagEnabled(): boolean {
+  return (globalThis as { __STIGMER_PERF__?: unknown }).__STIGMER_PERF__ === true;
+}
+
+/**
+ * Whether the SDK's dev-perf instrumentation may emit output. Evaluated per call
+ * (not cached) so a browser runtime toggle takes effect without a remount.
+ * Always `false` in production.
+ */
+export function isPerfLoggingEnabled(): boolean {
+  if (process.env.NODE_ENV === "production") return false;
+  return envFlagEnabled() || globalFlagEnabled();
+}

package/src/internal/dev/profiler-wrapper.tsx

@@ -1,8 +1,7 @@
 "use client";
 
 import { Profiler, type ProfilerOnRenderCallback, type ReactNode } from "react";
-
-const DEV = process.env.NODE_ENV !== "production";
+import { isPerfLoggingEnabled } from "./enabled.js";
 
 /** Log every Nth commit to avoid console flood during streaming. */
 const LOG_EVERY = 10;
@@ -31,9 +30,9 @@ const onRender: ProfilerOnRenderCallback = (
  * In dev mode, logs commit-level timing (`actualDuration`,
  * `baseDuration`, mount vs update phase) with sampled output.
  *
- * In production, React strips Profiler callbacks automatically, and
- * our dev gate ensures this component renders children with zero
- * overhead regardless.
+ * Off by default in every environment (and always in production) — enable via
+ * {@link isPerfLoggingEnabled}'s opt-in flags. When disabled, children render
+ * with zero Profiler overhead.
  */
 export function DevProfiler({
   id,
@@ -42,7 +41,7 @@ export function DevProfiler({
   readonly id: string;
   readonly children: ReactNode;
 }) {
-  if (!DEV) return children;
+  if (!isPerfLoggingEnabled()) return children;
 
   return (
     <Profiler id={id} onRender={onRender}>

package/src/internal/dev/use-key-stability.ts

@@ -1,6 +1,5 @@
 import { useRef } from "react";
-
-const DEV = process.env.NODE_ENV !== "production";
+import { isPerfLoggingEnabled } from "./enabled.js";
 
 /** Minimal shape expected from a keyed thread item. */
 interface KeyedItem {
@@ -25,7 +24,7 @@ interface KeyedItem {
 export function useKeyStability(items: readonly KeyedItem[]): void {
   const prevRef = useRef<readonly KeyedItem[] | null>(null);
 
-  if (!DEV) return;
+  if (!isPerfLoggingEnabled()) return;
 
   // Detect duplicate keys within the current render.
   const seen = new Map<string, number>();

package/src/internal/dev/use-render-tracer.ts

@@ -1,6 +1,5 @@
 import { useRef } from "react";
-
-const DEV = process.env.NODE_ENV !== "production";
+import { isPerfLoggingEnabled } from "./enabled.js";
 
 /**
  * Sampling interval: log every Nth render to avoid flooding the
@@ -12,8 +11,8 @@ const LOG_EVERY = 10;
  * Dev-only hook that tracks render count and reports which props
  * changed (by shallow referential equality) since the last render.
  *
- * In production builds the function body is dead-code-eliminated by
- * bundlers that replace `process.env.NODE_ENV` with `"production"`.
+ * Off by default in every environment (and always in production) — enable via
+ * {@link isPerfLoggingEnabled}'s opt-in flags.
  *
  * @param componentName - Stable label for console output.
  * @param props - Key/value map of props to track. Pass only the props
@@ -26,7 +25,7 @@ export function useRenderTracer(
   const countRef = useRef(0);
   const prevRef = useRef<Record<string, unknown> | null>(null);
 
-  if (!DEV) return;
+  if (!isPerfLoggingEnabled()) return;
 
   countRef.current += 1;
   const count = countRef.current;

package/src/internal/dev/use-stream-rate.ts

@@ -1,6 +1,5 @@
 import { useRef } from "react";
-
-const DEV = process.env.NODE_ENV !== "production";
+import { isPerfLoggingEnabled } from "./enabled.js";
 
 /** Rolling window size for interval statistics. */
 const WINDOW_SIZE = 30;
@@ -42,12 +41,13 @@ const NOOP_TRACKER: StreamRateTracker = {
  * loop (not during render), so it uses a ref-backed mutable object
  * rather than React state.
  *
- * In production the hook returns a no-op tracker.
+ * Returns a no-op tracker unless perf logging is explicitly enabled
+ * (see {@link isPerfLoggingEnabled}) — off by default in every environment.
  */
 export function useStreamRate(): StreamRateTracker {
   const stateRef = useRef<StreamRateState | null>(null);
 
-  if (!DEV) return NOOP_TRACKER;
+  if (!isPerfLoggingEnabled()) return NOOP_TRACKER;
 
   if (!stateRef.current) {
     stateRef.current = {

package/src/library/ResourceVisibilityControl.tsx

@@ -8,6 +8,7 @@ import { useSsoProvider } from "../identity-provider/useSsoProvider.js";
 import { VisibilityBadge, VisibilitySelector } from "./VisibilitySelector.js";
 import {
   blueprintVisibilityLevels,
+  environmentVisibilityLevels,
   INSTANCE_VISIBILITY_LEVELS,
 } from "./visibilityLevels.js";
 import {
@@ -28,6 +29,7 @@ const FGA_KIND: Record<VisibilityResourceKind, string> = {
   mcpServer: "mcp_server",
   agentInstance: "agent_instance",
   workflowInstance: "workflow_instance",
+  environment: "environment",
 };
 
 const INSTANCE_KINDS: ReadonlySet<VisibilityResourceKind> = new Set([
@@ -79,6 +81,9 @@ export interface ResourceVisibilityControlProps {
  *   set collapses to Private / Public.
  * - Instances: Private / Organization / Public — platform is excluded by
  *   design to preserve tenant isolation.
+ * - Environments: Private / Organization only — secret values never leave
+ *   the org boundary. In `local` mode there are no levels to choose (the
+ *   OSS backend is single-user), so the control degrades to a badge.
  *
  * The backend remains the enforcer (`ValidateVisibilityStep` rejects
  * platform without an IdP); the gate here only prevents offering an option
@@ -96,18 +101,23 @@ export function ResourceVisibilityControl({
   const deploymentMode = useDeploymentMode();
 
   const isInstance = INSTANCE_KINDS.has(kind);
+  const isEnvironment = kind === "environment";
   // The IdP lookup only matters for blueprints in cloud mode; passing null
   // makes the hook a stable no-op everywhere else.
   const idpLookupOrg =
-    !isInstance && deploymentMode === "cloud" ? (org ?? null) : null;
+    !isInstance && !isEnvironment && deploymentMode === "cloud"
+      ? (org ?? null)
+      : null;
   const { ssoProvider } = useSsoProvider(idpLookupOrg);
 
-  const options = isInstance
-    ? INSTANCE_VISIBILITY_LEVELS
-    : blueprintVisibilityLevels({
-        deploymentMode,
-        hasIdentityProvider: ssoProvider !== null,
-      });
+  const options = isEnvironment
+    ? environmentVisibilityLevels(deploymentMode)
+    : isInstance
+      ? INSTANCE_VISIBILITY_LEVELS
+      : blueprintVisibilityLevels({
+          deploymentMode,
+          hasIdentityProvider: ssoProvider !== null,
+        });
 
   const handleChange = useCallback(
     async (next: ApiResourceVisibility) => {
@@ -125,6 +135,12 @@ export function ResourceVisibilityControl({
 
   const badge = <VisibilityBadge visibility={visibility} className={className} />;
 
+  // Fewer than two levels means there is nothing to choose (e.g. an
+  // environment in local mode) — stay legible with the read-only badge.
+  if (options.length < 2) {
+    return badge;
+  }
+
   return (
     <PermissionGate
       resource={{ kind: FGA_KIND[kind], id: resourceId }}

package/src/library/__tests__/visibilityLevels.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { environmentVisibilityLevels } from "../visibilityLevels";
+
+describe("environmentVisibilityLevels", () => {
+  it("offers exactly Private and Organization in cloud mode", () => {
+    const levels = environmentVisibilityLevels("cloud");
+    expect(levels.map((l) => l.value)).toEqual([
+      ApiResourceVisibility.visibility_private,
+      ApiResourceVisibility.visibility_org,
+    ]);
+  });
+
+  it("never offers public or platform — secrets stay inside the org", () => {
+    for (const mode of ["cloud", "local"] as const) {
+      const values = environmentVisibilityLevels(mode).map((l) => l.value);
+      expect(values).not.toContain(ApiResourceVisibility.visibility_public);
+      expect(values).not.toContain(ApiResourceVisibility.visibility_platform);
+    }
+  });
+
+  it("confirms before escalating to org (credentials become runtime-usable org-wide)", () => {
+    const org = environmentVisibilityLevels("cloud").find(
+      (l) => l.value === ApiResourceVisibility.visibility_org,
+    );
+    expect(org?.confirmPrompt).toBeTruthy();
+    expect(org?.description).toContain("secret values stay hidden");
+  });
+
+  it("collapses to a single read-only level in local mode", () => {
+    expect(environmentVisibilityLevels("local")).toHaveLength(1);
+  });
+});

package/src/library/useUpdateVisibility.ts

@@ -14,7 +14,8 @@ export type VisibilityResourceKind =
   | "mcpServer"
   | "workflow"
   | "agentInstance"
-  | "workflowInstance";
+  | "workflowInstance"
+  | "environment";
 
 /** Return value of {@link useUpdateVisibility}. */
 export interface UseUpdateVisibilityReturn {
@@ -35,8 +36,10 @@ export interface UseUpdateVisibilityReturn {
  * Behavior hook that updates the visibility of a resource.
  *
  * Supports blueprints (Agent, Workflow, Skill, MCP Server) with the
- * full private/org/public/platform spectrum, and instances
- * (AgentInstance, WorkflowInstance) with private/org/public.
+ * full private/org/public/platform spectrum, instances
+ * (AgentInstance, WorkflowInstance) with private/org/public, and
+ * environments with private/org (secret values never leave the org
+ * boundary, so broader levels are rejected by the backend).
  *
  * Wraps the generated `stigmer.{kind}.updateVisibility()` SDK method
  * with loading and error state management. The hook is stateless with
@@ -99,6 +102,9 @@ export function useUpdateVisibility(
           case "workflowInstance":
             await stigmer.workflowInstance.updateVisibility(input);
             break;
+          case "environment":
+            await stigmer.environment.updateVisibility(input);
+            break;
         }
       } catch (err) {
         setError(toError(err));