@opengeni/sdk 0.8.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,13 +32,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsup"
-  },
-  "devDependencies": {
-    "@opengeni/contracts": "workspace:*",
-    "@opengeni/deployment": "workspace:*",
-    "tsup": "^8.5.0",
-    "typescript": "^6.0.3",
-    "zod": "^4.2.1"
+    "build": "tsup",
+    "prepublishOnly": "bash ../../scripts/prepublish-guard"
   }
 }

package/src/client.ts

@@ -18,6 +18,7 @@ import type {
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
   CapabilityInstallation,
+  AddDocumentRequest,
   ClientConfig,
   ClientSessionEventInput,
   CompactSessionContextResult,
@@ -32,6 +33,7 @@ import type {
   CreateFileUploadResponse,
   CreateGitHubAppManifestRequest,
   CreateGitHubAppManifestResponse,
+  CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
   CreateWorkspaceEnvironmentRequest,
@@ -45,6 +47,7 @@ import type {
   DiscoverMcpCapabilitiesResponse,
   Document,
   DocumentBase,
+  DocumentSearchRequest,
   DocumentSearchResponse,
   EnableCapabilityRequest,
   EnablePackRequest,
@@ -53,6 +56,8 @@ import type {
   GetPackResponse,
   GitHubAppInfo,
   GitHubRepositoriesResponse,
+  KnowledgeMemory,
+  KnowledgeMemorySearchRequest,
   ListApiKeysResponse,
   ListPacksResponse,
   // Bring-your-own-compute: the Machines dashboard + per-machine metrics (M10).
@@ -111,6 +116,7 @@ import type {
   PtyResizeRequest,
   PtyCloseRequest,
   ToolRef,
+  UpdateKnowledgeMemoryRequest,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
   UpdateSessionRequest,
@@ -974,7 +980,7 @@ export class OpenGeniClient {
   }
 
   /** Index an uploaded file into the base. The file must be `ready`. */
-  async addDocument(workspaceId: string, baseId: string, request: { fileId: string }): Promise<Document> {
+  async addDocument(workspaceId: string, baseId: string, request: AddDocumentRequest): Promise<Document> {
     return await this.requestJson<Document>("POST", `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`, request);
   }
 
@@ -1004,7 +1010,7 @@ export class OpenGeniClient {
   async searchDocuments(
     workspaceId: string,
     baseId: string,
-    request: { query: string; limit?: number },
+    request: Omit<DocumentSearchRequest, "baseIds">,
   ): Promise<DocumentSearchResponse> {
     return await this.requestJson<DocumentSearchResponse>(
       "POST",
@@ -1013,6 +1019,36 @@ export class OpenGeniClient {
     );
   }
 
+  async searchKnowledge(
+    workspaceId: string,
+    request: DocumentSearchRequest,
+  ): Promise<DocumentSearchResponse> {
+    return await this.requestJson<DocumentSearchResponse>("POST", `/v1/workspaces/${workspaceId}/knowledge/search`, request);
+  }
+
+  async listKnowledgeMemories(workspaceId: string, request: KnowledgeMemorySearchRequest = {}): Promise<KnowledgeMemory[]> {
+    const params = new URLSearchParams();
+    if (request.query) params.set("query", request.query);
+    if (request.status) params.set("status", request.status);
+    if (request.kind) params.set("kind", request.kind);
+    if (request.scope) params.set("scope", request.scope);
+    if (request.limit) params.set("limit", String(request.limit));
+    const query = params.toString();
+    return await this.requestJson<KnowledgeMemory[]>("GET", `/v1/workspaces/${workspaceId}/knowledge/memories${query ? `?${query}` : ""}`);
+  }
+
+  async getKnowledgeMemory(workspaceId: string, memoryId: string): Promise<KnowledgeMemory> {
+    return await this.requestJson<KnowledgeMemory>("GET", `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`);
+  }
+
+  async createKnowledgeMemory(workspaceId: string, request: CreateKnowledgeMemoryRequest): Promise<KnowledgeMemory> {
+    return await this.requestJson<KnowledgeMemory>("POST", `/v1/workspaces/${workspaceId}/knowledge/memories`, request);
+  }
+
+  async updateKnowledgeMemory(workspaceId: string, memoryId: string, request: UpdateKnowledgeMemoryRequest): Promise<KnowledgeMemory> {
+    return await this.requestJson<KnowledgeMemory>("PATCH", `/v1/workspaces/${workspaceId}/knowledge/memories/${memoryId}`, request);
+  }
+
   // --- Capability packs ------------------------------------------------------------------
 
   /** Built-in + registered packs, with the workspace's installations. */

package/src/index.ts

@@ -87,9 +87,15 @@ export type {
   CompactSessionContextResult,
   ClientSessionEventInput,
   CompleteFileUploadResponse,
+  ConnectionKind,
+  ConnectionMetadata,
+  ConnectionResponse,
+  ConnectionStatus,
+  AddDocumentRequest,
   CreateApiKeyRequest,
   CreateApiKeyResponse,
   CreateCapabilityCatalogItemRequest,
+  CreateConnectionRequest,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
   CreateDocumentBaseRequest,
@@ -97,6 +103,7 @@ export type {
   CreateFileUploadResponse,
   CreateGitHubAppManifestRequest,
   CreateGitHubAppManifestResponse,
+  CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
   CreateWorkspaceEnvironmentRequest,
@@ -104,6 +111,7 @@ export type {
   DiscoverMcpCapabilitiesResponse,
   Document,
   DocumentBase,
+  DocumentSearchMode,
   DocumentSearchRequest,
   DocumentSearchResponse,
   DocumentSearchResult,
@@ -123,12 +131,23 @@ export type {
   GitHubRepositoriesResponse,
   GitHubRepository,
   GoalSpec,
+  IntegrationClientMetadata,
   KnownPermission,
   KnownSessionEventType,
   KnownUsageEventType,
+  KnowledgeMemory,
+  KnowledgeMemoryKind,
+  KnowledgeMemorySearchRequest,
+  KnowledgeMemoryStatus,
+  KnowledgeSourceKind,
+  KnowledgeSourceRef,
   ListApiKeysResponse,
+  ListConnectionsResponse,
   ListPacksResponse,
   ListWorkspaceMembersResponse,
+  McpServerConnectionRef,
+  OAuthStartRequest,
+  OAuthStartResponse,
   PackInstallation,
   PackInstallationStatus,
   Permission,
@@ -194,6 +213,8 @@ export type {
   SessionTurn,
   SessionTurnSource,
   SessionTurnStatus,
+  ToolAuthNeededPayload,
+  UpdateConnectionRequest,
   // Channel-A structured services (P4.4) — A1 payloads + A2 request/response.
   SandboxCommandOutputDeltaPayload,
   FsChangeKind,
@@ -240,6 +261,7 @@ export type {
   PtyResizeRequest,
   PtyCloseRequest,
   ToolRef,
+  UpdateKnowledgeMemoryRequest,
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
   UpdateSessionRequest,

package/src/types.ts

@@ -262,6 +262,92 @@ export type SessionMcpServerMetadata = {
   credentialVersion: number;
 };
 
+export type ConnectionKind = "oauth2" | "api_key" | "app_install" | "delegated";
+export type ConnectionStatus = "active" | "needs_reauth" | "revoked" | "error";
+
+export type McpServerConnectionRef = {
+  connectionId?: string | undefined;
+  providerDomain: string;
+  kind?: ConnectionKind | undefined;
+  scopes?: string[] | undefined;
+  resource?: string | undefined;
+  subjectScope?: "workspace" | "subject" | undefined;
+};
+
+export type ConnectionMetadata = {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  providerDomain: string;
+  kind: ConnectionKind;
+  status: ConnectionStatus;
+  grantedScopes: string[];
+  expiresAt: string | null;
+  lastRefreshAt: string | null;
+  lastUsedAt: string | null;
+  lastError: string | null;
+  version: number;
+  metadata: Record<string, unknown>;
+  createdBySubjectId: string | null;
+  updatedBySubjectId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type CreateConnectionRequest = {
+  providerDomain: string;
+  kind: ConnectionKind;
+  subjectId?: string | null | undefined;
+  credential: Record<string, unknown>;
+  grantedScopes?: string[] | undefined;
+  expiresAt?: string | null | undefined;
+  metadata?: Record<string, unknown> | undefined;
+};
+
+export type UpdateConnectionRequest = {
+  providerDomain?: string | undefined;
+  subjectId?: string | null | undefined;
+  kind?: ConnectionKind | undefined;
+  status?: ConnectionStatus | undefined;
+  credential?: Record<string, unknown> | undefined;
+  grantedScopes?: string[] | undefined;
+  expiresAt?: string | null | undefined;
+  metadata?: Record<string, unknown> | undefined;
+};
+
+export type ConnectionResponse = {
+  connection: ConnectionMetadata;
+};
+
+export type ListConnectionsResponse = {
+  connections: ConnectionMetadata[];
+};
+
+export type OAuthStartRequest = {
+  providerDomain?: string | undefined;
+  mcpUrl?: string | undefined;
+  resource?: string | undefined;
+  requestedScopes?: string[] | undefined;
+  returnPath?: string | undefined;
+  connectionId?: string | undefined;
+};
+
+export type OAuthStartResponse = {
+  state: string;
+  authorizationUrl: string | null;
+  expiresAt: string;
+};
+
+export type IntegrationClientMetadata = {
+  client_id: string;
+  client_name: "OpenGeni";
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: Array<"authorization_code" | "refresh_token">;
+  response_types: ["code"];
+};
+
 export type Session = {
   id: string;
   workspaceId: string;
@@ -270,6 +356,9 @@ export type Session = {
   initialMessage: string;
   title: string | null;
   titleSource: "user" | "agent" | null;
+  // Per-session agent persona/system instructions supplied at create; null when
+  // the session carried none. Org-visible metadata, never a timeline event.
+  instructions: string | null;
   resources: ResourceRef[];
   tools: ToolRef[];
   metadata: Record<string, unknown>;
@@ -343,6 +432,7 @@ export const SESSION_EVENT_TYPES = [
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  "tool.auth_needed",
   "agent.updated",
   "sandbox.operation.started",
   "sandbox.operation.completed",
@@ -398,6 +488,18 @@ export type SessionEvent = {
   turnId?: string | null | undefined;
 };
 
+export type ToolAuthNeededPayload = {
+  serverId: string;
+  toolName?: string | null | undefined;
+  providerDomain: string;
+  connectionId?: string | null | undefined;
+  reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed";
+  scopes?: string[] | undefined;
+  resource?: string | undefined;
+  authorizationUrl?: string | undefined;
+  subjectId?: string | null | undefined;
+};
+
 // Payload shapes for the high-traffic event types. `SessionEvent.payload` is
 // `unknown` on the wire; these are the documented shapes producers emit today.
 export type AgentTextDeltaPayload = { text: string };
@@ -611,6 +713,11 @@ export type ScheduledTask = {
 
 export type CreateSessionRequest = {
   initialMessage: string;
+  // Per-session agent persona/system instructions (org-visible metadata, not a
+  // secret). Delivered system-level, composed AFTER the per-workspace persona —
+  // how a host supplies per-agent-type prompts without leaking them into the
+  // user-visible timeline. Trimmed, non-empty, max 32768 chars.
+  instructions?: string | undefined;
   resources?: ResourceRef[] | undefined;
   tools?: ToolRef[] | undefined;
   metadata?: Record<string, unknown> | undefined;
@@ -673,9 +780,12 @@ export const KNOWN_PERMISSIONS = [
   "github:manage",
   "github:use",
   "api_keys:manage",
+  "connections:read",
+  "connections:write",
   "environments:manage",
   "environments:use",
   "mcp_servers:attach",
+  "toolspace:call",
   "goals:manage",
   "enrollments:read",
   "enrollments:manage",
@@ -1186,6 +1296,8 @@ export type UploadFileInput = {
 // --- Documents -------------------------------------------------------------------
 
 export type DocumentStatus = "queued" | "indexing" | "ready" | "failed";
+export type KnowledgeSourceKind = "manual_upload" | "meeting_transcript" | "repository" | "email" | "chat" | "document" | "web" | "other";
+export type DocumentSearchMode = "hybrid" | "vector" | "keyword";
 
 export type DocumentBase = {
   id: string;
@@ -1206,6 +1318,15 @@ export type Document = {
   parser: string;
   chunkCount: number;
   error: string | null;
+  sourceKind: KnowledgeSourceKind;
+  sourceUri: string | null;
+  sourceExternalId: string | null;
+  sourceTitle: string | null;
+  sourceAuthor: string | null;
+  sourceCreatedAt: string | null;
+  sourceUpdatedAt: string | null;
+  sourceVersion: string | null;
+  aclTags: string[];
   createdAt: string;
   updatedAt: string;
 };
@@ -1219,8 +1340,20 @@ export type DocumentSearchResult = {
   title: string;
   text: string;
   score: number;
+  matchType: DocumentSearchMode;
+  vectorScore: number | null;
+  keywordScore: number | null;
   chunkIndex: number;
   metadata: Record<string, unknown>;
+  sourceKind: KnowledgeSourceKind;
+  sourceUri: string | null;
+  sourceExternalId: string | null;
+  sourceTitle: string | null;
+  sourceAuthor: string | null;
+  sourceCreatedAt: string | null;
+  sourceUpdatedAt: string | null;
+  sourceVersion: string | null;
+  aclTags: string[];
 };
 
 export type CreateDocumentBaseRequest = {
@@ -1228,8 +1361,26 @@ export type CreateDocumentBaseRequest = {
   description?: string | undefined;
 };
 
+export type AddDocumentRequest = {
+  fileId: string;
+  title?: string | undefined;
+  sourceKind?: KnowledgeSourceKind | undefined;
+  sourceUri?: string | undefined;
+  sourceExternalId?: string | undefined;
+  sourceTitle?: string | undefined;
+  sourceAuthor?: string | undefined;
+  sourceCreatedAt?: string | undefined;
+  sourceUpdatedAt?: string | undefined;
+  sourceVersion?: string | undefined;
+  aclTags?: string[] | undefined;
+};
+
 export type DocumentSearchRequest = {
   query: string;
+  baseIds?: string[] | undefined;
+  mode?: DocumentSearchMode | undefined;
+  sourceKinds?: KnowledgeSourceKind[] | undefined;
+  aclTags?: string[] | undefined;
   limit?: number | undefined;
 };
 
@@ -1237,6 +1388,64 @@ export type DocumentSearchResponse = {
   results: DocumentSearchResult[];
 };
 
+export type KnowledgeMemoryStatus = "proposed" | "approved" | "rejected";
+export type KnowledgeMemoryKind = "semantic" | "episodic" | "procedural" | "decision" | "preference";
+
+export type KnowledgeSourceRef = {
+  kind: "document_chunk" | "document" | "session_event" | "memory" | "external";
+  id: string;
+  uri?: string | undefined;
+  title?: string | undefined;
+  metadata?: Record<string, unknown> | undefined;
+};
+
+export type KnowledgeMemory = {
+  id: string;
+  workspaceId: string;
+  status: KnowledgeMemoryStatus;
+  kind: KnowledgeMemoryKind;
+  scope: string;
+  text: string;
+  sourceRefs: KnowledgeSourceRef[];
+  confidence: number;
+  metadata: Record<string, unknown>;
+  createdBySessionId: string | null;
+  reviewedBy: string | null;
+  reviewedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type CreateKnowledgeMemoryRequest = {
+  status?: KnowledgeMemoryStatus | undefined;
+  kind?: KnowledgeMemoryKind | undefined;
+  scope?: string | undefined;
+  text: string;
+  sourceRefs?: KnowledgeSourceRef[] | undefined;
+  confidence?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
+  createdBySessionId?: string | undefined;
+};
+
+export type UpdateKnowledgeMemoryRequest = {
+  status?: KnowledgeMemoryStatus | undefined;
+  kind?: KnowledgeMemoryKind | undefined;
+  scope?: string | undefined;
+  text?: string | undefined;
+  sourceRefs?: KnowledgeSourceRef[] | undefined;
+  confidence?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
+  reviewedBy?: string | undefined;
+};
+
+export type KnowledgeMemorySearchRequest = {
+  query?: string | undefined;
+  status?: KnowledgeMemoryStatus | undefined;
+  kind?: KnowledgeMemoryKind | undefined;
+  scope?: string | undefined;
+  limit?: number | undefined;
+};
+
 // --- Capability packs ---------------------------------------------------------
 
 export type CapabilityPackConnectorAuthModel =
@@ -1397,10 +1606,14 @@ export type GetPackResponse = {
 
 export type CapabilityKind = "pack" | "mcp" | "api" | "skill" | "plugin";
 
-export type CapabilitySource = "built_in" | "configured" | "public_registry" | "manual";
+export type CapabilitySource = "built_in" | "configured" | "public_registry" | "registry" | "manual";
 
 export type CapabilityInstallationStatus = "active" | "disabled";
 
+export type CapabilityCatalogAuthKind = "oauth2" | "api_key" | "none" | "unknown";
+
+export type CapabilityCatalogTier = "verified" | "community";
+
 export type CapabilityRuntime = {
   available: boolean;
   mcpServerId?: string | undefined;
@@ -1422,6 +1635,18 @@ export type CapabilityCatalogItem = {
   endpointUrl: string | null;
   installUrl: string | null;
   authModel: string | null;
+  providerDomain: string | null;
+  surfaceType: string | null;
+  transport: string | null;
+  mcpUrl: string | null;
+  authKind: CapabilityCatalogAuthKind | null;
+  credentialFacts: Record<string, unknown>[];
+  tier: CapabilityCatalogTier | null;
+  provenance: string | null;
+  logoAssetPath: string | null;
+  importBatchId: string | null;
+  stale: boolean;
+  staleAt: string | null;
   tools: ToolRef[];
   runtime: CapabilityRuntime;
   enabled: boolean;
@@ -1467,6 +1692,7 @@ export type CreateCapabilityCatalogItemRequest = {
 export type EnableCapabilityRequest = {
   config?: Record<string, unknown> | undefined;
   metadata?: Record<string, unknown> | undefined;
+  connectionRef?: McpServerConnectionRef | undefined;
   /**
    * Credential headers for remote MCP capabilities. Write-only: encrypted at
    * rest, injected only into the runtime MCP client, never returned by the
@@ -1696,6 +1922,10 @@ export type MachineView = {
   os: string;
   arch: string;
   hasDisplay: boolean;
+  /** Non-null only when a display exists but capture is blocked (macOS Screen
+   *  Recording / TCC not granted) — the UI can surface "display: capture not
+   *  granted". null == capture permitted OR headless. */
+  desktopUnavailableReason?: string | null | undefined;
   allowScreenControl: boolean;
   sharedSessionCount: number;
   lastSeenAt: string | null;