@opengeni/sdk 4.0.2 → 5.0.3-canary.0

package/src/site-tool-bridge.ts

@@ -0,0 +1,141 @@
+import { OpenGeniApiError } from "./errors";
+import { siteSessionPath, type SiteHttpRequest } from "./site-http";
+import type { OpenGeniSiteToolCatalog } from "./site";
+import type { OpenGeniWorkspaceTools } from "./tools";
+import type { ToolGatewayCallRequest, ToolGatewayCallResponse, ToolGatewayIdentity } from "./types";
+
+export type SiteToolCallRequest = ToolGatewayCallRequest & {
+  siteArtifactId: string;
+  siteVersionId: string;
+};
+export type SiteToolCaller = (input: {
+  workspaceId: string;
+  request: SiteToolCallRequest;
+  signal: AbortSignal;
+}) => Promise<ToolGatewayCallResponse>;
+export type SiteToolBridge = {
+  fetch?: (request: SiteHttpRequest, signal: AbortSignal) => Promise<Response>;
+  catalog: (options: { signal: AbortSignal }) => Promise<OpenGeniSiteToolCatalog>;
+  call: (
+    request: ToolGatewayCallRequest,
+    options: { signal: AbortSignal },
+  ) => Promise<ToolGatewayCallResponse>;
+};
+export type CreateSiteToolBridgeOptions = {
+  workspaceTools: Pick<OpenGeniWorkspaceTools, "$catalog">;
+  workspaceId: string;
+  artifactId: string;
+  siteVersionId: string;
+  requestedTools: readonly ToolGatewayIdentity[];
+  callTool: SiteToolCaller;
+  isCatalogStale?: (error: unknown) => boolean;
+  /** Optional authenticated host transport for the host-bound workspace API.
+   * Omit to expose tools only. Site-provided authorization headers are never forwarded. */
+  fetchResponse?: (path: string, init: RequestInit) => Promise<Response>;
+};
+
+/** Host-side bridge for the opaque Site frame. Supply an authenticated transport;
+ * the server independently checks live viewer access and the exact Site version.
+ * Recreate on actor/version change. Never take these pinned fields from HTML. */
+export function createSiteToolBridge(input: CreateSiteToolBridgeOptions): SiteToolBridge {
+  const allowed = new Set(input.requestedTools.map(identityKey));
+  let projectedCatalog: OpenGeniSiteToolCatalog | null = null;
+  const loadCatalog = async ({
+    signal,
+    refresh = false,
+  }: {
+    signal: AbortSignal;
+    refresh?: boolean;
+  }): Promise<OpenGeniSiteToolCatalog> => {
+    signal.throwIfAborted();
+    if (projectedCatalog && !refresh) return projectedCatalog;
+    const current = await input.workspaceTools.$catalog({
+      signal,
+      ...(refresh ? { refresh } : {}),
+    });
+    signal.throwIfAborted();
+    if (current.workspaceId !== input.workspaceId)
+      throw new Error("Site catalog workspace mismatch");
+    projectedCatalog = {
+      version: current.version,
+      generation: current.generation,
+      digest: current.digest,
+      createdAt: current.createdAt,
+      entries: current.entries.filter((entry) => allowed.has(identityKey(entry.identity))),
+    };
+    return projectedCatalog;
+  };
+  return {
+    ...(input.fetchResponse
+      ? {
+          fetch: async (message: SiteHttpRequest, signal: AbortSignal) => {
+            const path = siteSessionPath(
+              message.path,
+              input.workspaceId,
+              message.method,
+              input.artifactId,
+            );
+            const headers = new Headers();
+            headers.set("x-opengeni-site-id", input.artifactId);
+            headers.set("x-opengeni-site-version", input.siteVersionId);
+            for (const [name, value] of message.headers) {
+              if (["content-type", "accept", "last-event-id"].includes(name.toLowerCase()))
+                headers.set(name, value);
+            }
+            return input.fetchResponse!(path, {
+              method: message.method,
+              signal,
+              headers: Object.fromEntries(headers),
+              ...(message.body === undefined ? {} : { body: message.body }),
+            });
+          },
+        }
+      : {}),
+    catalog: loadCatalog,
+    call: async (request, { signal }) => {
+      if (!allowed.has(identityKey(request.identity)))
+        throw new Error("This tool is not available to the Site");
+      const call = async (refresh = false) => {
+        const catalog = await loadCatalog({ signal, refresh });
+        if (
+          !catalog.entries.some(
+            (entry) => identityKey(entry.identity) === identityKey(request.identity),
+          )
+        )
+          throw new Error("This requested tool is not enabled in the workspace");
+        return input.callTool({
+          workspaceId: input.workspaceId,
+          signal,
+          request: {
+            ...(request.operationId ? { operationId: request.operationId } : {}),
+            catalogDigest: catalog.digest,
+            identity: request.identity,
+            arguments: request.arguments,
+            siteArtifactId: input.artifactId,
+            siteVersionId: input.siteVersionId,
+          },
+        });
+      };
+      try {
+        return await call();
+      } catch (error) {
+        // Only pre-execution catalog rejection permits one retry. Never retry
+        // transport failures, expired credentials or uncertain tool effects.
+        if (!(input.isCatalogStale ?? isSiteCatalogStaleError)(error)) throw error;
+        projectedCatalog = null;
+        return await call(true);
+      }
+    },
+  };
+}
+
+export function isSiteCatalogStaleError(error: unknown): boolean {
+  return (
+    error instanceof OpenGeniApiError &&
+    error.status === 409 &&
+    error.details?.code === "catalog_stale"
+  );
+}
+function identityKey(identity: ToolGatewayIdentity): string {
+  return `${identity.serverId}\u0000${identity.toolName}`;
+}

package/src/site.ts

@@ -1,3 +1,10 @@
+export { createSiteToolBridge, isSiteCatalogStaleError } from "./site-tool-bridge";
+export type {
+  SiteToolBridge,
+  SiteToolCaller,
+  SiteToolCallRequest,
+  CreateSiteToolBridgeOptions,
+} from "./site-tool-bridge";
 import {
   OpenGeniToolsClient,
   type OpenGeniToolTransport,

package/src/types.ts

@@ -694,6 +694,7 @@ export type McpConnectionAuthoritySelection = {
 export type McpServerConnectionRef = {
   connectionId?: string | undefined;
   authoritySource?: "host" | undefined;
+  hostBinding?: { bindingId: string; generation: number } | undefined;
   provider?: string | undefined;
   providerDomain: string;
   kind?: ConnectionKind | undefined;
@@ -879,6 +880,7 @@ export type FikenInstallRequest = {
 };
 
 export type FikenOAuthStartRequest = {
+  returnPath?: string | undefined;
   /** Existing Fiken connection to re-authorize in place (reconnect). */
   connectionId?: string | undefined;
 };
@@ -1177,6 +1179,8 @@ export type OAuthStartRequest = {
   resource?: string | undefined;
   requestedScopes?: string[] | undefined;
   returnPath?: string | undefined;
+  /** Exact trusted-host destination; requires verified external-user mode. */
+  returnUrl?: string | undefined;
   connectionId?: string | undefined;
   ownership?: ConnectionOwnership | undefined;
   oauthClient?:
@@ -1472,7 +1476,7 @@ export type Session = {
   /** Agent access scope; absent on servers before the agent-access release. */
   agentAccess?: SessionAgentAccess | undefined;
   /** Opaque end-user label; null when the session carries none. */
-  endUser?: SessionEndUser | null | undefined;
+  scopeSubjectId?: SessionScopeSubjectId | null | undefined;
   /** Memory scope; absent on servers before the agent-access release. */
   memoryScope?: SessionMemoryScope | undefined;
   createdAt: string;
@@ -2857,6 +2861,10 @@ export type ScheduledTask = {
 };
 
 export type CreateSessionRequest = {
+  /** Opt-in host grants for a direct external-user initial turn. */
+  selectedHostMcpDelegations?:
+    | { serverId: string; delegationId: string; generation: number }[]
+    | undefined;
   /** Omitted: defaults/inheritance; []: no bundled guidance. Children cannot widen. */
   bundledSkillIds?: BundledSkillId[] | undefined;
   // Optional UUID preallocated by an embedding host so it can durably link its
@@ -2929,14 +2937,15 @@ export type CreateSessionRequest = {
   // on the platform (the chat facade defaults to "session").
   agentAccess?: SessionAgentAccess | undefined;
   /** Opaque end-user label inside the workspace. Not a subject, not authority. */
-  endUser?: SessionEndUser | undefined;
-  /** Which Memory the agent reads and where it saves; "user" requires `endUser`. */
+  /** Select identity with server-side asUser(), not session creation data. */
+  scopeSubjectId?: never;
+  /** Which Memory the agent reads and where it saves; "user" requires `scopeSubjectId`. */
   memoryScope?: SessionMemoryScope | undefined;
 };
 
 export type SessionAgentAccess = "session" | "user" | "workspace";
-export type SessionEndUser = { source: string; id: string };
-export type SessionMemoryScope = "workspace" | "user" | "session" | "off";
+export type SessionScopeSubjectId = string;
+export type SessionMemoryScope = "workspace" | "user" | "off";
 
 // --- Access, workspaces, API keys -------------------------------------------
 
@@ -4610,7 +4619,7 @@ export type ListOrganizationSessionsOptions = {
   /** `nextCursor` from the previous page. */
   cursor?: string | undefined;
   /** Keep only sessions labelled with this exact end user. */
-  endUser?: { source: string; id: string } | undefined;
+  scopeSubjectId?: string | undefined;
   /** Keep only sessions in this exact lifecycle state. */
   status?: SessionStatus | undefined;
   signal?: AbortSignal | undefined;
@@ -5222,6 +5231,7 @@ export type CreateAgentScheduledTaskRequest = {
   runMode?: ScheduledTaskRunMode | undefined;
   targetSessionId?: string | null | undefined;
   connectionAuthorities?: McpConnectionAuthoritySelection[] | undefined;
+  selectedHostMcpDelegations?: CreateSessionRequest["selectedHostMcpDelegations"];
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   agentConfig: ScheduledTaskAgentConfigInput;
   status?: ScheduledTaskStatus | undefined;
@@ -5252,6 +5262,7 @@ export type UpdateScheduledTaskRequest = {
   runMode?: ScheduledTaskRunMode | undefined;
   targetSessionId?: string | null | undefined;
   connectionAuthorities?: McpConnectionAuthoritySelection[] | undefined;
+  selectedHostMcpDelegations?: CreateSessionRequest["selectedHostMcpDelegations"];
   overlapPolicy?: ScheduledTaskOverlapPolicy | undefined;
   action?: ScheduledTaskAction | undefined;
   agentConfig?: ScheduledTaskAgentConfigInput | undefined;
@@ -7925,6 +7936,7 @@ export type UserMessageEventInput = {
     expectedDraftRevision?: number | undefined;
     mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[] | undefined;
     connectionAuthorities?: McpConnectionAuthoritySelection[] | undefined;
+    selectedHostMcpDelegations?: CreateSessionRequest["selectedHostMcpDelegations"];
     personalResourceAttachment?: PersonalResourceAttachmentIntent | undefined;
   };
 };