@opengeni/react 0.26.0 → 0.26.2

package/dist/machines.d.ts

@@ -1,7 +1,7 @@
 import { MachineState, MetricSample, MachineView, MachineKind, MachinesResponse } from '@opengeni/sdk';
 export { MachineKind, MachineMetricsSeriesResponse, MachineState, MachineView, MachinesResponse, MetricSample } from '@opengeni/sdk';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { C as ClientOverride } from './session-context-rgrfElMl.js';
+import { C as ClientOverride } from './session-context-CAjlaeZb.js';
 
 /**
  * The three connection-status pill values the UI surfaces across the dashboard,

package/dist/machines.js

@@ -24,9 +24,9 @@ import {
   healthPulses,
   pointsFor,
   useMachines
-} from "./chunk-YU5PGUK7.js";
+} from "./chunk-BC6RKIHS.js";
 import "./chunk-TK7G6XLT.js";
-import "./chunk-HIWPQYWI.js";
+import "./chunk-HQFPO7VX.js";
 import "./chunk-M7X4JZOD.js";
 export {
   CONNECTION_STATUS_META,

package/dist/{session-Du_FsrZ1.d.ts → session-LsampPc6.d.ts}

@@ -1,10 +1,10 @@
-import { C as ClientOverride, E as EmbeddedSessionClientOverride, e as EmbeddedSessionMcpApprovalPolicyClientOverride, f as EmbeddedHumanInputClientOverride } from './session-context-rgrfElMl.js';
+import { k as EmbeddedSessionReadClientOverride, a as EmbeddedSessionClientOverride, l as EmbeddedGoalClientOverride, m as EmbeddedSessionMcpApprovalPolicyClientOverride, n as EmbeddedSessionLineageClientOverride, o as EmbeddedHumanInputClientOverride } from './session-context-CAjlaeZb.js';
 import { Session, SessionEvent, StreamConnectionState, SessionStatus, SessionGoal, SessionControlResponse, SessionMcpServerMetadata, SessionMcpApprovalPolicy, UpdateSessionMcpApprovalPolicyResponse, SessionLineageResponse, HumanInputQuestion, SessionHumanInputRequest, SubmitHumanInputResponseRequest } from '@opengeni/sdk';
-import { S as SessionEventFeedOptions } from './use-composer-BnEzheSk.js';
-import { e as TimelineItem, d as TimelineGroup } from './use-turn-queue-3rkJwjFv.js';
-import './use-file-attachments-C0kpHrs9.js';
+import { S as SessionEventFeedOptions } from './use-composer-ClHy1rkL.js';
+import { e as TimelineItem, d as TimelineGroup } from './use-turn-queue-aDnQvzVz.js';
+import './use-file-attachments-BmT8WtqO.js';
 
-type UseSessionOptions = ClientOverride & SessionEventFeedOptions & {
+type UseSessionOptions = EmbeddedSessionReadClientOverride & SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
     pollIntervalMs?: number | undefined;
 };
@@ -91,7 +91,7 @@ declare function boundBrowserSessionEventWindow(events: readonly SessionEvent[],
 
 /** Event types that change the session goal (set/updated/completed/paused/...). */
 declare function isGoalEvent(event: Pick<SessionEvent, "type">): boolean;
-type UseGoalOptions = ClientOverride & SessionEventFeedOptions & {
+type UseGoalOptions = EmbeddedGoalClientOverride & SessionEventFeedOptions & {
     /** Optional safety-net polling (ms). Off by default — event refreshes drive updates. */
     pollIntervalMs?: number | undefined;
 };
@@ -169,7 +169,7 @@ type UseSessionMcpApprovalPolicyResult = {
  */
 declare function useSessionMcpApprovalPolicy(sessionId: string | null | undefined, serverId: string | null | undefined, options?: UseSessionMcpApprovalPolicyOptions): UseSessionMcpApprovalPolicyResult;
 
-type UseSessionLineageOptions = ClientOverride & {
+type UseSessionLineageOptions = EmbeddedSessionLineageClientOverride & {
     events?: SessionEvent[] | undefined;
     /** Refresh interval (ms). Off by default. */
     pollIntervalMs?: number | undefined;

package/dist/{session-context-rgrfElMl.d.ts → session-context-CAjlaeZb.d.ts}

@@ -18,10 +18,20 @@ type SessionClientLike = Pick<OpenGeniClient, "getClientConfig" | "getSession" |
 type EmbeddedSessionClientLike = Pick<OpenGeniClient, "getSession" | "listEvents" | "streamEvents" | "getComposerDraft" | "saveComposerDraft" | "sendMessage" | "steerMessage" | "getQueue" | "moveQueueItem" | "editQueueItem" | "steerQueueItem" | "deleteQueueItem" | "pauseSession" | "resumeSession" | "sendApprovalDecision"> & {
     setWorkspaceInferenceState?: OpenGeniClient["setWorkspaceInferenceState"] | undefined;
 };
-/** Session client refinement required only by structured human-input hooks. */
-type EmbeddedHumanInputSessionClientLike = EmbeddedSessionClientLike & Pick<OpenGeniClient, "listHumanInputRequests" | "getHumanInputRequest" | "submitHumanInputResponse">;
-/** Session client refinement required only by MCP approval-policy hooks. */
-type EmbeddedSessionMcpApprovalPolicyClientLike = EmbeddedSessionClientLike & Pick<OpenGeniClient, "updateSessionMcpApprovalPolicy">;
+/** Event-read surface shared by hooks that optionally tail a session. */
+type EmbeddedSessionEventClientLike = Pick<OpenGeniClient, "getSession" | "streamEvents">;
+/** Exact client surface required by {@link useSession}. */
+type EmbeddedSessionReadClientLike = EmbeddedSessionEventClientLike & Pick<OpenGeniClient, "getSession" | "updateSession">;
+/** Exact client surface required by {@link useGoal}. */
+type EmbeddedGoalClientLike = EmbeddedSessionEventClientLike & Pick<OpenGeniClient, "getGoal" | "updateGoal" | "deleteGoal">;
+/** Exact client surface required by {@link useSessionLineage}. */
+type EmbeddedSessionLineageClientLike = EmbeddedSessionEventClientLike & Pick<OpenGeniClient, "getSessionLineage">;
+/** Exact client surface required by {@link useFileAttachments}. */
+type EmbeddedFileAttachmentClientLike = Pick<OpenGeniClient, "uploadFile">;
+/** Exact client surface required by structured human-input hooks. */
+type EmbeddedHumanInputSessionClientLike = EmbeddedSessionEventClientLike & Pick<OpenGeniClient, "listHumanInputRequests" | "submitHumanInputResponse">;
+/** Exact client surface required by MCP approval-policy hooks. */
+type EmbeddedSessionMcpApprovalPolicyClientLike = EmbeddedSessionEventClientLike & Pick<OpenGeniClient, "updateSessionMcpApprovalPolicy">;
 
 type OpenGeniContextValue = {
     client: SessionClientLike;
@@ -47,6 +57,22 @@ type EmbeddedSessionMcpApprovalPolicyClientOverride = {
     client?: EmbeddedSessionMcpApprovalPolicyClientLike | undefined;
     workspaceId?: string | undefined;
 };
+type EmbeddedSessionReadClientOverride = {
+    client?: EmbeddedSessionReadClientLike | undefined;
+    workspaceId?: string | undefined;
+};
+type EmbeddedGoalClientOverride = {
+    client?: EmbeddedGoalClientLike | undefined;
+    workspaceId?: string | undefined;
+};
+type EmbeddedSessionLineageClientOverride = {
+    client?: EmbeddedSessionLineageClientLike | undefined;
+    workspaceId?: string | undefined;
+};
+type EmbeddedFileAttachmentClientOverride = {
+    client?: EmbeddedFileAttachmentClientLike | undefined;
+    workspaceId?: string | undefined;
+};
 /** Resolve client + workspace from explicit overrides or the provider. */
 declare function useOpenGeni(override?: ClientOverride): OpenGeniContextValue;
 /**
@@ -55,4 +81,4 @@ declare function useOpenGeni(override?: ClientOverride): OpenGeniContextValue;
  */
 declare function useOpenGeniClient(override?: Pick<ClientOverride, "client">): SessionClientLike;
 
-export { type ClientOverride as C, type EmbeddedSessionClientOverride as E, type OpenGeniContextValue as O, type SessionClientLike as S, type EmbeddedHumanInputSessionClientLike as a, type EmbeddedSessionClientLike as b, type EmbeddedSessionMcpApprovalPolicyClientLike as c, useOpenGeniClient as d, type EmbeddedSessionMcpApprovalPolicyClientOverride as e, type EmbeddedHumanInputClientOverride as f, useOpenGeni as u };
+export { type ClientOverride as C, type EmbeddedFileAttachmentClientOverride as E, type OpenGeniContextValue as O, type SessionClientLike as S, type EmbeddedSessionClientOverride as a, type EmbeddedFileAttachmentClientLike as b, type EmbeddedGoalClientLike as c, type EmbeddedHumanInputSessionClientLike as d, type EmbeddedSessionClientLike as e, type EmbeddedSessionEventClientLike as f, type EmbeddedSessionLineageClientLike as g, type EmbeddedSessionMcpApprovalPolicyClientLike as h, type EmbeddedSessionReadClientLike as i, useOpenGeniClient as j, type EmbeddedSessionReadClientOverride as k, type EmbeddedGoalClientOverride as l, type EmbeddedSessionMcpApprovalPolicyClientOverride as m, type EmbeddedSessionLineageClientOverride as n, type EmbeddedHumanInputClientOverride as o, useOpenGeni as u };

package/dist/{session-ui-BqQDH7YV.d.ts → session-ui-BPOV-tuY.d.ts}

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { SessionHumanInputRequest, SubmitHumanInputResponseRequest, HumanInputQuestion, HumanInputAnswer, SessionEvent, SessionStatus } from '@opengeni/sdk';
 import { ReactNode, ComponentType } from 'react';
-import { h as UseTurnQueueResult, f as ToolCallItem, e as TimelineItem, a as AgentMessageItem, i as UserMessageItem, b as AuthNeededItem } from './use-turn-queue-3rkJwjFv.js';
-import { C as ComposerState } from './use-composer-BnEzheSk.js';
+import { h as UseTurnQueueResult, f as ToolCallItem, e as TimelineItem, a as AgentMessageItem, i as UserMessageItem, b as AuthNeededItem } from './use-turn-queue-aDnQvzVz.js';
+import { C as ComposerState } from './use-composer-ClHy1rkL.js';
 
 /** The sole human prompt queue: compact above Goal, Agents, and composer. */
 type QueueSurfaceCommonProps = {

package/dist/session-ui.d.ts

@@ -1,7 +1,7 @@
-export { H as HumanInputAnswerDraft, a as HumanInputForm, b as HumanInputFormMessages, d as HumanInputFormProps, M as MessageTimeline, e as MessageTimelineProps, Q as QueueSurface, f as QueueSurfaceProps, g as TimelineRow } from './session-ui-BqQDH7YV.js';
+export { H as HumanInputAnswerDraft, a as HumanInputForm, b as HumanInputFormMessages, d as HumanInputFormProps, M as MessageTimeline, e as MessageTimelineProps, Q as QueueSurface, f as QueueSurfaceProps, g as TimelineRow } from './session-ui-BPOV-tuY.js';
 import 'react/jsx-runtime';
 import '@opengeni/sdk';
 import 'react';
-import './use-turn-queue-3rkJwjFv.js';
-import './session-context-rgrfElMl.js';
-import './use-composer-BnEzheSk.js';
+import './use-turn-queue-aDnQvzVz.js';
+import './session-context-CAjlaeZb.js';
+import './use-composer-ClHy1rkL.js';

package/dist/session.d.ts

@@ -1,6 +1,6 @@
-export { E as ClientOverride, f as HumanInputClientOverride, a as HumanInputSessionClientLike, b as SessionClientLike, c as SessionMcpApprovalPolicyClientLike, e as SessionMcpApprovalPolicyClientOverride } from './session-context-rgrfElMl.js';
-export { P as PendingApproval, a as PendingHumanInputRequest, f as SessionEventsConnectionState, U as UseGoalOptions, g as UseGoalResult, h as UseHumanInputRequestsOptions, i as UseHumanInputRequestsResult, j as UseSessionControlOptions, k as UseSessionControlResult, l as UseSessionEventsOptions, m as UseSessionEventsResult, n as UseSessionLineageOptions, o as UseSessionLineageResult, p as UseSessionMcpApprovalPolicyOptions, q as UseSessionMcpApprovalPolicyResult, r as UseSessionOptions, s as UseSessionResult, t as approvalsFromRequiresAction, v as buildTimeline, w as creditExhaustedFromEvents, x as extractSessionRef, y as groupTimeline, z as humanInputRequestFromEvent, A as isGoalEvent, C as isHumanInputEvent, D as isLineageRefreshEvent, E as isSessionMcpApprovalPolicyEvent, F as isTitleEvent, G as projectPendingApprovals, H as projectPendingHumanInputRequests, I as sessionStatusFromEvents, J as toolDisplayName, K as useGoal, L as useHumanInputRequests, M as useSession, N as useSessionControl, O as useSessionEvents, Q as useSessionLineage, R as useSessionMcpApprovalPolicy } from './session-Du_FsrZ1.js';
-export { a as ComposerSendExtras, C as ComposerState, F as FILE_ONLY_MESSAGE_TEXT, U as UseComposerOptions, c as composeSendInput, s as shouldSteerOnKey, b as shouldSubmitOnKey, u as useComposer } from './use-composer-BnEzheSk.js';
-export { F as FileAttachment, a as UseFileAttachmentsOptions, U as UseFileAttachmentsResult, u as useFileAttachments } from './use-file-attachments-C0kpHrs9.js';
-export { A as ActivityItem, a as AgentMessageItem, b as AuthNeededItem, G as GoalItem, M as MemoryItem, N as NoticeItem, Q as QueueMutationKind, R as ReasoningItem, S as SandboxItem, c as SessionStatusItem, d as TimelineGroup, e as TimelineItem, f as ToolCallItem, g as TurnEndItem, T as TurnOutcome, U as UseTurnQueueOptions, h as UseTurnQueueResult, i as UserMessageItem, k as WorkerCompletionItem, W as WorkerItem, j as isTurnQueueEvent, u as useTurnQueue } from './use-turn-queue-3rkJwjFv.js';
+export { a as ClientOverride, b as FileAttachmentClientLike, E as FileAttachmentClientOverride, c as GoalClientLike, l as GoalClientOverride, o as HumanInputClientOverride, d as HumanInputSessionClientLike, e as SessionClientLike, g as SessionLineageClientLike, n as SessionLineageClientOverride, h as SessionMcpApprovalPolicyClientLike, m as SessionMcpApprovalPolicyClientOverride, i as SessionReadClientLike, k as SessionReadClientOverride } from './session-context-CAjlaeZb.js';
+export { P as PendingApproval, a as PendingHumanInputRequest, f as SessionEventsConnectionState, U as UseGoalOptions, g as UseGoalResult, h as UseHumanInputRequestsOptions, i as UseHumanInputRequestsResult, j as UseSessionControlOptions, k as UseSessionControlResult, l as UseSessionEventsOptions, m as UseSessionEventsResult, n as UseSessionLineageOptions, o as UseSessionLineageResult, p as UseSessionMcpApprovalPolicyOptions, q as UseSessionMcpApprovalPolicyResult, r as UseSessionOptions, s as UseSessionResult, t as approvalsFromRequiresAction, v as buildTimeline, w as creditExhaustedFromEvents, x as extractSessionRef, y as groupTimeline, z as humanInputRequestFromEvent, A as isGoalEvent, C as isHumanInputEvent, D as isLineageRefreshEvent, E as isSessionMcpApprovalPolicyEvent, F as isTitleEvent, G as projectPendingApprovals, H as projectPendingHumanInputRequests, I as sessionStatusFromEvents, J as toolDisplayName, K as useGoal, L as useHumanInputRequests, M as useSession, N as useSessionControl, O as useSessionEvents, Q as useSessionLineage, R as useSessionMcpApprovalPolicy } from './session-LsampPc6.js';
+export { a as ComposerSendExtras, C as ComposerState, F as FILE_ONLY_MESSAGE_TEXT, U as UseComposerOptions, c as composeSendInput, s as shouldSteerOnKey, b as shouldSubmitOnKey, u as useComposer } from './use-composer-ClHy1rkL.js';
+export { F as FileAttachment, a as UseFileAttachmentsOptions, U as UseFileAttachmentsResult, u as useFileAttachments } from './use-file-attachments-BmT8WtqO.js';
+export { A as ActivityItem, a as AgentMessageItem, b as AuthNeededItem, G as GoalItem, M as MemoryItem, N as NoticeItem, Q as QueueMutationKind, R as ReasoningItem, S as SandboxItem, c as SessionStatusItem, d as TimelineGroup, e as TimelineItem, f as ToolCallItem, g as TurnEndItem, T as TurnOutcome, U as UseTurnQueueOptions, h as UseTurnQueueResult, i as UserMessageItem, k as WorkerCompletionItem, W as WorkerItem, j as isTurnQueueEvent, u as useTurnQueue } from './use-turn-queue-aDnQvzVz.js';
 import '@opengeni/sdk';

package/dist/session.js

@@ -18,15 +18,15 @@ import {
   useSessionLineage,
   useSessionMcpApprovalPolicy,
   useTurnQueue
-} from "./chunk-MP6237JB.js";
+} from "./chunk-NBYNFI5T.js";
 import {
   FILE_ONLY_MESSAGE_TEXT,
   composeSendInput,
   shouldSteerOnKey,
   shouldSubmitOnKey,
   useComposer
-} from "./chunk-F4CFWKVI.js";
-import "./chunk-HIWPQYWI.js";
+} from "./chunk-4F2YLLHP.js";
+import "./chunk-HQFPO7VX.js";
 import {
   buildTimeline,
   creditExhaustedFromEvents,

package/dist/{use-composer-BnEzheSk.d.ts → use-composer-ClHy1rkL.d.ts}

@@ -1,5 +1,5 @@
 import { SessionEvent, EffectiveControlResumeOption, ComposerDraft, ResourceRef, SendMessageInput, EffectiveSessionControl } from '@opengeni/sdk';
-import { E as EmbeddedSessionClientOverride } from './session-context-rgrfElMl.js';
+import { a as EmbeddedSessionClientOverride } from './session-context-CAjlaeZb.js';
 
 type SessionEventFeedOptions = {
     /**

package/dist/{use-file-attachments-C0kpHrs9.d.ts → use-file-attachments-BmT8WtqO.d.ts}

@@ -1,7 +1,7 @@
 import { FileAsset, FileResourceRef } from '@opengeni/sdk';
-import { C as ClientOverride } from './session-context-rgrfElMl.js';
+import { E as EmbeddedFileAttachmentClientOverride } from './session-context-CAjlaeZb.js';
 
-type UseFileAttachmentsOptions = ClientOverride & {
+type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
     /**
      * Only files matching this predicate are accepted by {@link
      * UseFileAttachmentsResult.addFromPaste} (the clipboard path). Defaults to

package/dist/{use-turn-queue-3rkJwjFv.d.ts → use-turn-queue-aDnQvzVz.d.ts}

@@ -1,6 +1,6 @@
 import { ToolAuthNeededPayload, ResourceRef, ToolRef, SessionStatus, SessionQueueSnapshot, SessionTurn, EffectiveSessionControl, ComposerDraft, SessionEvent } from '@opengeni/sdk';
-import { E as EmbeddedSessionClientOverride } from './session-context-rgrfElMl.js';
-import { S as SessionEventFeedOptions } from './use-composer-BnEzheSk.js';
+import { a as EmbeddedSessionClientOverride } from './session-context-CAjlaeZb.js';
+import { S as SessionEventFeedOptions } from './use-composer-ClHy1rkL.js';
 
 type UserMessageItem = {
     kind: "user-message";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/react",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "React hooks and styled components for OpenGeni: live session streaming, chat composer, message timeline, session status, and fleet views — token-themed (CSS variables), dark-first, built on Tailwind v4 + Radix + Motion.",
   "license": "Apache-2.0",
   "repository": {
@@ -66,7 +66,7 @@
     "@dnd-kit/utilities": "3.2.2",
     "@fontsource-variable/noto-sans-arabic": "5.2.10",
     "@fontsource-variable/noto-sans-jp": "5.2.10",
-    "@opengeni/sdk": "^0.26.0",
+    "@opengeni/sdk": "^0.26.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.8.0",
     "motion": "^12.0.0",

package/src/client.ts

@@ -145,13 +145,28 @@ export type EmbeddedSessionClientLike = Pick<
   setWorkspaceInferenceState?: OpenGeniClient["setWorkspaceInferenceState"] | undefined;
 };
 
-/** Session client refinement required only by structured human-input hooks. */
-export type EmbeddedHumanInputSessionClientLike = EmbeddedSessionClientLike &
-  Pick<
-    OpenGeniClient,
-    "listHumanInputRequests" | "getHumanInputRequest" | "submitHumanInputResponse"
-  >;
+/** Event-read surface shared by hooks that optionally tail a session. */
+export type EmbeddedSessionEventClientLike = Pick<OpenGeniClient, "getSession" | "streamEvents">;
 
-/** Session client refinement required only by MCP approval-policy hooks. */
-export type EmbeddedSessionMcpApprovalPolicyClientLike = EmbeddedSessionClientLike &
+/** Exact client surface required by {@link useSession}. */
+export type EmbeddedSessionReadClientLike = EmbeddedSessionEventClientLike &
+  Pick<OpenGeniClient, "getSession" | "updateSession">;
+
+/** Exact client surface required by {@link useGoal}. */
+export type EmbeddedGoalClientLike = EmbeddedSessionEventClientLike &
+  Pick<OpenGeniClient, "getGoal" | "updateGoal" | "deleteGoal">;
+
+/** Exact client surface required by {@link useSessionLineage}. */
+export type EmbeddedSessionLineageClientLike = EmbeddedSessionEventClientLike &
+  Pick<OpenGeniClient, "getSessionLineage">;
+
+/** Exact client surface required by {@link useFileAttachments}. */
+export type EmbeddedFileAttachmentClientLike = Pick<OpenGeniClient, "uploadFile">;
+
+/** Exact client surface required by structured human-input hooks. */
+export type EmbeddedHumanInputSessionClientLike = EmbeddedSessionEventClientLike &
+  Pick<OpenGeniClient, "listHumanInputRequests" | "submitHumanInputResponse">;
+
+/** Exact client surface required by MCP approval-policy hooks. */
+export type EmbeddedSessionMcpApprovalPolicyClientLike = EmbeddedSessionEventClientLike &
   Pick<OpenGeniClient, "updateSessionMcpApprovalPolicy">;

package/src/components/sandbox-workspace.tsx

@@ -90,6 +90,8 @@ function captureDegradedMessage(reason: string): string {
       return "Workspace capture is incomplete because repository discovery timed out. Live files remain authoritative.";
     case "repository_discovery_result_limit_exceeded":
       return "Workspace capture is incomplete because the repository limit was exceeded. Live files remain authoritative.";
+    case "repository_read_unavailable":
+      return "Workspace capture is incomplete because repository changes could not be read. Live files remain authoritative.";
     default:
       return "Workspace capture is incomplete because repository discovery failed. Live files remain authoritative.";
   }

package/src/hooks/internal.ts

@@ -1,6 +1,6 @@
 import type { SessionEvent } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
-import type { EmbeddedSessionClientLike } from "../client";
+import type { EmbeddedSessionEventClientLike } from "../client";
 
 export type AsyncListState<T> = {
   data: T | null;
@@ -215,7 +215,7 @@ export type SessionEventFeedOptions = {
  * `events` log or tails the stream directly (reconnect handled by the SDK).
  */
 export function useSessionEventTrigger(
-  client: EmbeddedSessionClientLike,
+  client: EmbeddedSessionEventClientLike,
   workspaceId: string,
   sessionId: string | null | undefined,
   match: (event: SessionEvent) => boolean,

package/src/hooks/use-file-attachments.ts

@@ -1,8 +1,11 @@
 import type { FileAsset, FileResourceRef } from "@opengeni/sdk";
 import { useCallback, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../session-context";
+import {
+  useEmbeddedFileAttachments,
+  type EmbeddedFileAttachmentClientOverride,
+} from "../session-context";
 
-export type UseFileAttachmentsOptions = ClientOverride & {
+export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
   /**
    * Only files matching this predicate are accepted by {@link
    * UseFileAttachmentsResult.addFromPaste} (the clipboard path). Defaults to
@@ -78,7 +81,7 @@ const isImage = (file: File): boolean => file.type.startsWith("image/");
 export function useFileAttachments(
   options: UseFileAttachmentsOptions = {},
 ): UseFileAttachmentsResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId } = useEmbeddedFileAttachments(options);
   const pasteFilter = options.pasteFilter ?? isImage;
   const [attachments, setAttachments] = useState<FileAttachment[]>([]);
   // Keep the source File per attachment id so a failed upload can be retried

package/src/hooks/use-goal.ts

@@ -1,6 +1,6 @@
 import { OpenGeniApiError, type SessionEvent, type SessionGoal } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../session-context";
+import { useEmbeddedGoal, type EmbeddedGoalClientOverride } from "../session-context";
 import {
   useDebouncedCallback,
   useMutationRunner,
@@ -30,7 +30,7 @@ export function isGoalRefreshEvent(event: Pick<SessionEvent, "type">): boolean {
   );
 }
 
-export type UseGoalOptions = ClientOverride &
+export type UseGoalOptions = EmbeddedGoalClientOverride &
   SessionEventFeedOptions & {
     /** Optional safety-net polling (ms). Off by default — event refreshes drive updates. */
     pollIntervalMs?: number | undefined;
@@ -71,7 +71,7 @@ export function useGoal(
   sessionId: string | null | undefined,
   options: UseGoalOptions = {},
 ): UseGoalResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId } = useEmbeddedGoal(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const sharedEvents = options.events;
   const sharedFeed = sharedEvents !== undefined;

package/src/hooks/use-session-lineage.ts

@@ -1,9 +1,12 @@
 import type { SessionEvent, SessionLineageResponse } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef } from "react";
-import { useOpenGeni, type ClientOverride } from "../session-context";
+import {
+  useEmbeddedSessionLineage,
+  type EmbeddedSessionLineageClientOverride,
+} from "../session-context";
 import { useDebouncedCallback, usePolledValue, useSessionEventTrigger } from "./internal";
 
-export type UseSessionLineageOptions = ClientOverride & {
+export type UseSessionLineageOptions = EmbeddedSessionLineageClientOverride & {
   events?: SessionEvent[] | undefined;
   /** Refresh interval (ms). Off by default. */
   pollIntervalMs?: number | undefined;
@@ -58,7 +61,7 @@ export function useSessionLineage(
   options: UseSessionLineageOptions = {},
 ): UseSessionLineageResult {
   const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
-    useOpenGeni(options);
+    useEmbeddedSessionLineage(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const load = useCallback(
     async () =>

package/src/hooks/use-session.ts

@@ -1,6 +1,6 @@
 import type { Session, SessionEvent } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../session-context";
+import { useEmbeddedSessionRead, type EmbeddedSessionReadClientOverride } from "../session-context";
 import {
   useMutationRunner,
   usePolledValue,
@@ -8,7 +8,7 @@ import {
   type SessionEventFeedOptions,
 } from "./internal";
 
-export type UseSessionOptions = ClientOverride &
+export type UseSessionOptions = EmbeddedSessionReadClientOverride &
   SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
     pollIntervalMs?: number | undefined;
@@ -38,7 +38,7 @@ export function useSession(
   options: UseSessionOptions = {},
 ): UseSessionResult {
   const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
-    useOpenGeni(options);
+    useEmbeddedSessionRead(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const [override, setOverride] = useState<Session | null>(null);
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();

package/src/index.ts

@@ -8,8 +8,13 @@
 //   @source "../node_modules/@opengeni/react/src";
 
 export type {
+  EmbeddedFileAttachmentClientLike,
+  EmbeddedGoalClientLike,
   EmbeddedHumanInputSessionClientLike,
+  EmbeddedSessionEventClientLike,
+  EmbeddedSessionLineageClientLike,
   EmbeddedSessionMcpApprovalPolicyClientLike,
+  EmbeddedSessionReadClientLike,
   EmbeddedSessionClientLike,
   SessionClientLike,
 } from "./client";

package/src/session-context.ts

@@ -1,9 +1,13 @@
 import type { StreamConnectionState, WorkspaceControlEvent } from "@opengeni/sdk";
 import { createContext, useContext } from "react";
 import type {
+  EmbeddedFileAttachmentClientLike,
+  EmbeddedGoalClientLike,
   EmbeddedHumanInputSessionClientLike,
-  EmbeddedSessionMcpApprovalPolicyClientLike,
   EmbeddedSessionClientLike,
+  EmbeddedSessionLineageClientLike,
+  EmbeddedSessionMcpApprovalPolicyClientLike,
+  EmbeddedSessionReadClientLike,
   SessionClientLike,
 } from "./client";
 
@@ -46,22 +50,61 @@ export type EmbeddedSessionMcpApprovalPolicyClientOverride = {
   workspaceId?: string | undefined;
 };
 
+export type EmbeddedSessionReadClientOverride = {
+  client?: EmbeddedSessionReadClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
+export type EmbeddedGoalClientOverride = {
+  client?: EmbeddedGoalClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
+export type EmbeddedSessionLineageClientOverride = {
+  client?: EmbeddedSessionLineageClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
+export type EmbeddedFileAttachmentClientOverride = {
+  client?: EmbeddedFileAttachmentClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
 export type EmbeddedSessionContextValue = Omit<OpenGeniContextValue, "client"> & {
   client: EmbeddedSessionClientLike;
 };
 
-/** Resolve client + workspace from explicit overrides or the provider. */
-export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue {
+type EmbeddedClientOverride<TClient> = {
+  client?: TClient | undefined;
+  workspaceId?: string | undefined;
+};
+
+type EmbeddedClientContextValue<TClient> = Omit<OpenGeniContextValue, "client"> & {
+  client: TClient;
+};
+
+function useEmbeddedClientRefinement<TClient extends object>(
+  override: EmbeddedClientOverride<TClient>,
+  requiredMethods: readonly string[],
+  hookName: string,
+): EmbeddedClientContextValue<TClient> {
   const context = useContext(OpenGeniContext);
-  const client = override.client ?? context?.client;
+  const candidate = override.client ?? context?.client;
   const workspaceId = override.workspaceId ?? context?.workspaceId;
-  if (!client || !workspaceId) {
+  if (!candidate || !workspaceId) {
     throw new Error(
       "@opengeni/react: no OpenGeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
     );
   }
+  const methods = candidate as Record<string, unknown>;
+  const missing = requiredMethods.filter((method) => typeof methods[method] !== "function");
+  if (missing.length > 0) {
+    throw new Error(
+      `@opengeni/react: ${hookName} requires client method${missing.length === 1 ? "" : "s"} ${missing.join(", ")}.`,
+    );
+  }
   return {
-    client,
+    client: candidate as TClient,
     workspaceId,
     workspaceControlEvent: context?.workspaceControlEvent ?? null,
     workspaceControlConnectionState: context?.workspaceControlConnectionState ?? "idle",
@@ -70,14 +113,14 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
   };
 }
 
-/**
- * Resolve the narrow client required by the session-only hooks. The full
- * provider client is structurally compatible, while an explicit host proxy
- * only needs to expose session/event/composer/queue/control operations.
- */
-export function useEmbeddedSession(
-  override: EmbeddedSessionClientOverride = {},
-): EmbeddedSessionContextValue {
+function eventClientMethods(override: object, directMethods: readonly string[]): readonly string[] {
+  const hasSharedEventFeed =
+    "events" in override && (override as { events?: unknown }).events !== undefined;
+  return hasSharedEventFeed ? directMethods : ["getSession", "streamEvents", ...directMethods];
+}
+
+/** Resolve client + workspace from explicit overrides or the provider. */
+export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue {
   const context = useContext(OpenGeniContext);
   const client = override.client ?? context?.client;
   const workspaceId = override.workspaceId ?? context?.workspaceId;
@@ -96,6 +139,77 @@ export function useEmbeddedSession(
   };
 }
 
+/**
+ * Resolve the narrow client required by the session-only hooks. The full
+ * provider client is structurally compatible, while an explicit host proxy
+ * only needs to expose session/event/composer/queue/control operations.
+ */
+export function useEmbeddedSession(
+  override: EmbeddedSessionClientOverride = {},
+): EmbeddedSessionContextValue {
+  return useEmbeddedClientRefinement(
+    override,
+    [
+      "getSession",
+      "listEvents",
+      "streamEvents",
+      "getComposerDraft",
+      "saveComposerDraft",
+      "sendMessage",
+      "steerMessage",
+      "getQueue",
+      "moveQueueItem",
+      "editQueueItem",
+      "steerQueueItem",
+      "deleteQueueItem",
+      "pauseSession",
+      "resumeSession",
+      "sendApprovalDecision",
+    ],
+    "session hooks",
+  );
+}
+
+/** Resolve the exact client surface required by `useSession`. */
+export function useEmbeddedSessionRead(
+  override: EmbeddedSessionReadClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedSessionReadClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    eventClientMethods(override, ["getSession", "updateSession"]),
+    "useSession",
+  );
+}
+
+/** Resolve the exact client surface required by `useGoal`. */
+export function useEmbeddedGoal(
+  override: EmbeddedGoalClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedGoalClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    eventClientMethods(override, ["getGoal", "updateGoal", "deleteGoal"]),
+    "useGoal",
+  );
+}
+
+/** Resolve the exact client surface required by `useSessionLineage`. */
+export function useEmbeddedSessionLineage(
+  override: EmbeddedSessionLineageClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedSessionLineageClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    eventClientMethods(override, ["getSessionLineage"]),
+    "useSessionLineage",
+  );
+}
+
+/** Resolve the exact client surface required by `useFileAttachments`. */
+export function useEmbeddedFileAttachments(
+  override: EmbeddedFileAttachmentClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedFileAttachmentClientLike> {
+  return useEmbeddedClientRefinement(override, ["uploadFile"], "useFileAttachments");
+}
+
 /**
  * Resolve the structured-input refinement without widening the baseline
  * session-only proxy contract.
@@ -106,21 +220,11 @@ export function useEmbeddedHumanInputSession(override: EmbeddedHumanInputClientO
 > & {
   client: EmbeddedHumanInputSessionClientLike;
 } {
-  const embedded = useEmbeddedSession(override);
-  const client = embedded.client as Partial<EmbeddedHumanInputSessionClientLike>;
-  if (
-    typeof client.listHumanInputRequests !== "function" ||
-    typeof client.getHumanInputRequest !== "function" ||
-    typeof client.submitHumanInputResponse !== "function"
-  ) {
-    throw new Error(
-      "@opengeni/react: useHumanInputRequests requires listHumanInputRequests, getHumanInputRequest, and submitHumanInputResponse.",
-    );
-  }
-  return {
-    ...embedded,
-    client: client as EmbeddedHumanInputSessionClientLike,
-  };
+  return useEmbeddedClientRefinement(
+    override,
+    eventClientMethods(override, ["listHumanInputRequests", "submitHumanInputResponse"]),
+    "useHumanInputRequests",
+  );
 }
 
 /** Resolve the approval-policy refinement without widening session-only hosts. */
@@ -129,17 +233,11 @@ export function useEmbeddedSessionMcpApprovalPolicy(
 ): Omit<EmbeddedSessionContextValue, "client"> & {
   client: EmbeddedSessionMcpApprovalPolicyClientLike;
 } {
-  const embedded = useEmbeddedSession(override);
-  const client = embedded.client as Partial<EmbeddedSessionMcpApprovalPolicyClientLike>;
-  if (typeof client.updateSessionMcpApprovalPolicy !== "function") {
-    throw new Error(
-      "@opengeni/react: useSessionMcpApprovalPolicy requires updateSessionMcpApprovalPolicy.",
-    );
-  }
-  return {
-    ...embedded,
-    client: client as EmbeddedSessionMcpApprovalPolicyClientLike,
-  };
+  return useEmbeddedClientRefinement(
+    override,
+    eventClientMethods(override, ["getSession", "updateSessionMcpApprovalPolicy"]),
+    "useSessionMcpApprovalPolicy",
+  );
 }
 
 /**