@stigmer/react 3.1.7 → 3.1.8

package/src/session/__tests__/useSessionPageFlow.guest.test.tsx

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Guest-audience gating for useSessionPageFlow.
+//
+// A guest token cannot read the org default agent or derive the session's
+// agent (`agentInstance.get` → `agent.get` are FGA-denied — sharing writes
+// no tuples). The flow must put both lookups into their `null` no-op mode
+// and send follow-ups without an agent override, continuing on the
+// session's server-bound instance.
+// ---------------------------------------------------------------------------
+
+const mockSendFollowUp = vi.fn();
+
+const mockConv = {
+  session: { spec: { agentInstanceId: "inst_bound" } },
+  isLoading: false,
+  completedExecutions: [] as unknown[],
+  activeStreamExecution: null,
+  workspaceEntries: [] as unknown[],
+  submitApproval: vi.fn(),
+  sendFollowUp: mockSendFollowUp,
+};
+vi.mock("../useSessionConversation", () => ({
+  useSessionConversation: () => mockConv,
+}));
+
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({ agent: { getByReference: vi.fn() } }),
+}));
+
+const useDefaultAgentSpy = vi.fn((_org: string | null) => ({
+  agent: null,
+  isLoading: false,
+  error: null,
+}));
+vi.mock("../../agent", () => ({
+  useDefaultAgent: (org: string | null) => useDefaultAgentSpy(org),
+}));
+
+const mockWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  removeEntry: vi.fn(),
+  clear: vi.fn(),
+};
+vi.mock("../../workspace", () => ({
+  useWorkspaceEntries: () => mockWorkspace,
+}));
+
+const mockSessionVariables = {
+  variables: [],
+  isEmpty: true,
+  clear: vi.fn(),
+};
+vi.mock("../../execution/useSessionVariables", () => ({
+  useSessionVariables: () => mockSessionVariables,
+}));
+
+vi.mock("../usePersistedModel", () => ({
+  usePersistedModel: () => ["model-x", vi.fn()] as const,
+}));
+
+const useAgentRefFromSessionSpy = vi.fn((_instanceId: string | null) => ({
+  agentRef: null,
+}));
+vi.mock("../useAgentRefFromSession", () => ({
+  useAgentRefFromSession: (instanceId: string | null) =>
+    useAgentRefFromSessionSpy(instanceId),
+}));
+
+import { useSessionPageFlow } from "../useSessionPageFlow";
+
+const OPTS = { sessionId: "ses_1", org: "acme" };
+
+describe("useSessionPageFlow — guest audience", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("disables the session→agent derivation and default-agent lookup", () => {
+    renderHook(() => useSessionPageFlow({ ...OPTS, audience: "guest" }));
+
+    expect(useAgentRefFromSessionSpy).toHaveBeenCalledWith(null);
+    expect(useDefaultAgentSpy).toHaveBeenCalledWith(null);
+  });
+
+  it("keeps both lookups active for other audiences", () => {
+    renderHook(() => useSessionPageFlow(OPTS));
+
+    expect(useAgentRefFromSessionSpy).toHaveBeenCalledWith("inst_bound");
+    expect(useDefaultAgentSpy).toHaveBeenCalledWith("acme");
+  });
+
+  it("sends follow-ups without an agent override", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, audience: "guest" }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up");
+    });
+
+    expect(mockSendFollowUp).toHaveBeenCalledTimes(1);
+    // No override: the execution continues on the session's bound instance.
+    expect(mockSendFollowUp.mock.calls[0][1].agentInstanceId).toBeUndefined();
+  });
+});

package/src/session/audience.ts

@@ -12,9 +12,17 @@
  *   Agent/Plan mode, and attaches workspaces, but never reconfigures
  *   the agent. The organisms lock the agent and hide the integrator
  *   pickers, in both the composer and the inspector's Setup tab.
+ * - `"guest"` — an anonymous visitor of a shared agent's public page or
+ *   embed, authenticated by a guest token. Pure chat: everything
+ *   `"endUser"` hides plus the model, harness, and Agent/Plan pickers,
+ *   attachments, the workspace picker, and the session panel. Guest is
+ *   behavioral, not just cosmetic — the organisms also skip the
+ *   org-level reads a guest principal cannot make (default-agent
+ *   resolution, session→agent derivation, personal environments) and
+ *   never fall back to the org's default agent.
  *
- * A preset rather than individual flags: "end user" is a product intent,
- * and keeping it in one place lets the SDK evolve what that presentation
- * means without breaking embedders.
+ * A preset rather than individual flags: each audience is a product
+ * intent, and keeping it in one place lets the SDK evolve what that
+ * presentation means without breaking embedders.
  */
-export type SessionAudience = "integrator" | "endUser";
+export type SessionAudience = "integrator" | "endUser" | "guest";

package/src/session/facets/ChangesTab.tsx

@@ -45,14 +45,16 @@ export function ChangesTab({
   const { writeBacks, hasWriteBacks } = useSessionWriteBacks(executions);
 
   if (hasWriteBacks) {
+    // Dense row groups matching the Artifacts facet's list — gap separates
+    // entries only in multi-repo sessions (single-entry lists stay seamless).
     return (
-      <div role="list" className="space-y-2">
+      <ul role="list" className="flex flex-col gap-3">
         {writeBacks.map((entry) => (
-          <div key={entry.writeBack.workspaceEntryName} role="listitem">
+          <li key={entry.writeBack.workspaceEntryName}>
             <WriteBackCard writeBack={entry.writeBack} />
-          </div>
+          </li>
         ))}
-      </div>
+      </ul>
     );
   }
 

package/src/session/useNewSessionFlow.ts

@@ -17,6 +17,7 @@ import type { ExecutionTargetOption } from "./execution-target.js";
 import { useExecutionTarget } from "../execution-target-context.js";
 import { useRunnerAdapter } from "../runner-adapter.js";
 import { resolveExecutionRuntimeEnv, type RuntimeEnvProvider } from "./runtime-env.js";
+import type { SessionAudience } from "./audience.js";
 
 const DEFAULT_AGENT_TIMEOUT_MS = 10_000;
 
@@ -80,6 +81,17 @@ export interface UseNewSessionFlowOptions {
    * @default DEFAULT_HARNESS ("native")
    */
   readonly defaultHarness?: HarnessOption;
+  /**
+   * Who this flow serves. `"guest"` adapts the orchestration to the
+   * guest principal's permission model: the org default-agent lookup
+   * (which a guest token cannot read) is skipped, and submission
+   * requires an explicit agent resolution instead of falling back to
+   * the org's default agent — a shared-agent page must never run
+   * anything but the pinned shared agent. See {@link SessionAudience}.
+   *
+   * @default "integrator"
+   */
+  readonly audience?: SessionAudience;
 }
 
 /** Return value of {@link useNewSessionFlow}. */
@@ -184,6 +196,7 @@ export function useNewSessionFlow(
   options: UseNewSessionFlowOptions,
 ): UseNewSessionFlowReturn {
   const { org, onSessionCreated, onError, getRuntimeEnv, defaultHarness } = options;
+  const isGuest = options.audience === "guest";
   const contextTarget = useExecutionTarget();
   const executionTarget = options.executionTarget ?? contextTarget;
   const adapter = useRunnerAdapter();
@@ -200,12 +213,15 @@ export function useNewSessionFlow(
   const { getModel, isLoading: isModelsLoading } = useModelRegistry({ harness });
   const { create: createSession } = useCreateSession();
   const { create: createExecution } = useCreateAgentExecution();
+  // Guests cannot read the org default agent (and must never run it) —
+  // `null` puts the hook in its stable no-op mode, and the submit path
+  // below fails closed instead of falling back.
   const {
     agent: defaultAgent,
     isLoading: isDefaultAgentLoading,
     error: defaultAgentError,
     waitForResolution: waitForDefaultAgent,
-  } = useDefaultAgent(org);
+  } = useDefaultAgent(isGuest ? null : org);
   const workspace = useWorkspaceEntries();
   const sessionVariables = useSessionVariables();
 
@@ -315,6 +331,14 @@ export function useNewSessionFlow(
               agentRef,
             }));
           }
+        } else if (isGuest) {
+          // Fail closed: a guest session is only ever created against the
+          // pinned shared agent's resolution. Reaching here means the pin
+          // has not been applied yet (or was cleared) — never substitute
+          // the org default agent for an anonymous visitor.
+          throw new Error(
+            "This agent is still loading. Please try again in a moment.",
+          );
         } else {
           let resolvedInstanceId = defaultAgent?.status?.defaultInstanceId;
           if (!resolvedInstanceId) {
@@ -375,6 +399,7 @@ export function useNewSessionFlow(
     [
       isSubmitting,
       org,
+      isGuest,
       harness,
       executionTarget,
       adapter,

package/src/session/useSessionPageFlow.ts

@@ -18,6 +18,7 @@ import { resolveExecutionRuntimeEnv, type RuntimeEnvProvider } from "./runtime-e
 import { useAgentRefFromSession } from "./useAgentRefFromSession.js";
 import { usePersistedModel, type UsePersistedModelReturn } from "./usePersistedModel.js";
 import { specMcpUsagesToInput, specSkillRefsToInput } from "./session-spec-converters.js";
+import type { SessionAudience } from "./audience.js";
 
 /**
  * Well-known Daytona sandbox workspace root. Used as the SDK safety-net
@@ -43,6 +44,18 @@ export interface UseSessionPageFlowOptions {
    * {@link RuntimeEnvProvider}.
    */
   readonly getRuntimeEnv?: RuntimeEnvProvider;
+  /**
+   * Who this flow serves. `"guest"` adapts the orchestration to the
+   * guest principal's permission model: the session→agent derivation
+   * (`agentInstance.get` → `agent.get`) and the org default-agent
+   * lookup — reads a guest token cannot make — are skipped. Follow-ups
+   * then carry no agent override and simply continue on the session's
+   * bound instance, which is exactly right for a shared-agent page.
+   * See {@link SessionAudience}.
+   *
+   * @default "integrator"
+   */
+  readonly audience?: SessionAudience;
 }
 
 /** Return value of {@link useSessionPageFlow}. */
@@ -226,6 +239,7 @@ export function useSessionPageFlow(
   options: UseSessionPageFlowOptions,
 ): UseSessionPageFlowReturn {
   const { sessionId, org, getRuntimeEnv } = options;
+  const isGuest = options.audience === "guest";
 
   const stigmer = useStigmer();
   const conv = useSessionConversation(sessionId, org);
@@ -291,9 +305,17 @@ export function useSessionPageFlow(
   // Agent — derive from session, allow mid-session changes
   // -------------------------------------------------------------------------
 
+  // Guests skip agent derivation entirely (`null` = the hooks' stable
+  // no-op): the reads are FGA-denied for a guest token, and a guest
+  // never overrides the session's agent — `resolution` stays null, so
+  // follow-ups continue on the bound instance without an override.
   const sessionInstanceId = conv.session?.spec?.agentInstanceId ?? null;
-  const { agentRef: derivedAgentRef } = useAgentRefFromSession(sessionInstanceId);
-  const { agent: defaultAgent, isLoading: isDefaultAgentLoading } = useDefaultAgent(org);
+  const { agentRef: derivedAgentRef } = useAgentRefFromSession(
+    isGuest ? null : sessionInstanceId,
+  );
+  const { agent: defaultAgent, isLoading: isDefaultAgentLoading } = useDefaultAgent(
+    isGuest ? null : org,
+  );
 
   const [agentRef, setAgentRef] = useState<ResourceRef | null>(null);
   const [resolution, setResolution] = useState<AgentResolution | null>(null);