@opengeni/sdk 0.25.0 → 0.26.0

package/src/errors.ts

@@ -2,33 +2,97 @@
 export class OpenGeniApiError extends Error {
   readonly status: number;
   readonly code: string | undefined;
+  readonly retryable: boolean;
+  readonly correlationId: string | undefined;
+  /** True only when an uncontrolled transport failed after a mutation may have been accepted. */
+  readonly outcomeUnknown: boolean;
   readonly body: string;
 
-  constructor(status: number, body: string) {
+  constructor(
+    status: number,
+    body: string,
+    options: {
+      code?: string | undefined;
+      retryable?: boolean | undefined;
+      correlationId?: string | undefined;
+      outcomeUnknown?: boolean | undefined;
+      displayMessage?: string | undefined;
+      mutation?: boolean | undefined;
+    } = {},
+  ) {
     const decoded = decodeApiErrorBody(body);
-    super(`OpenGeni API ${status}: ${decoded.message ?? (body || "(empty body)")}`);
+    const correlationId = decoded?.requestId ?? boundedCorrelationId(options.correlationId);
+    const gatewayFailure = status >= 502 && status <= 504;
+    const fromResponse = options.mutation !== undefined;
+    const message = decoded?.message ?? (fromResponse ? "Request failed." : body || "(empty body)");
+    const displayMessage =
+      options.displayMessage ??
+      (gatewayFailure && fromResponse
+        ? "OpenGeni is temporarily unavailable — retry."
+        : `OpenGeni API ${status}: ${message}`);
+    super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);
     this.name = "OpenGeniApiError";
     this.status = status;
-    this.code = decoded.code;
-    this.body = body;
+    this.code =
+      options.code ??
+      decoded?.code ??
+      (gatewayFailure && fromResponse ? "upstream_unavailable" : undefined);
+    this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);
+    this.correlationId = correlationId;
+    this.outcomeUnknown =
+      options.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
+    this.body = !fromResponse || decoded ? body : "";
   }
 }
 
-function decodeApiErrorBody(body: string): { code?: string; message?: string } {
-  if (!body) return {};
+function decodeApiErrorBody(body: string): {
+  code: string | undefined;
+  message: string | undefined;
+  requestId: string | undefined;
+  retryable: boolean | undefined;
+} | null {
+  if (!body) return null;
   try {
     const decoded: unknown = JSON.parse(body);
-    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return {};
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
     const record = decoded as Record<string, unknown>;
+    const nested =
+      record.error && typeof record.error === "object" && !Array.isArray(record.error)
+        ? (record.error as Record<string, unknown>)
+        : record;
+    const code = boundedApiField(nested.code);
+    const message = boundedApiField(nested.message);
+    const requestId = boundedCorrelationId(nested.requestId);
+    const retryable = typeof nested.retryable === "boolean" ? nested.retryable : undefined;
+    if (!code && !message && !requestId && retryable === undefined) return null;
     return {
-      ...(typeof record.code === "string" && record.code ? { code: record.code } : {}),
-      ...(typeof record.message === "string" && record.message ? { message: record.message } : {}),
+      code,
+      message,
+      requestId,
+      retryable,
     };
   } catch {
-    return {};
+    return null;
   }
 }
 
+function boundedApiField(value: unknown): string | undefined {
+  if (typeof value !== "string") return;
+  const bytes = new TextEncoder().encode(value);
+  return bytes.byteLength <= 512 ? value : new TextDecoder().decode(bytes.slice(0, 512));
+}
+
+function retryableApiStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
+function boundedCorrelationId(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length > 128 || !/^[\w.:-]+$/.test(value)) {
+    return;
+  }
+  return value;
+}
+
 /** A short-lived session-list snapshot cursor can no longer be continued. */
 export class OpenGeniSessionListCursorError extends OpenGeniApiError {}
 
@@ -67,14 +131,6 @@ export function isAbortError(error: unknown): boolean {
  * permanent and surface to the caller instead.
  */
 export function isRetryableStreamError(error: unknown): boolean {
-  if (error instanceof OpenGeniApiError) {
-    return (
-      error.status === 408 ||
-      error.status === 409 ||
-      error.status === 425 ||
-      error.status === 429 ||
-      error.status >= 500
-    );
-  }
+  if (error instanceof OpenGeniApiError) return error.retryable;
   return error instanceof TypeError;
 }

package/src/index.ts

@@ -53,6 +53,29 @@ export type {
 } from "./stream";
 export { streamWorkspaceControlEvents } from "./workspace-control-stream";
 export type { WorkspaceControlStreamTransport } from "./workspace-control-stream";
+export { normalizeWorkspaceInstructionPolicyRoleKey } from "./workspace-instruction-policies";
+export type {
+  ActivateWorkspaceInstructionPolicyRequest,
+  CreateWorkspaceInstructionPolicyDraftRequest,
+  ImportLegacyWorkspaceInstructionPolicyDraftRequest,
+  RollbackWorkspaceInstructionPolicyRequest,
+  WorkspaceInstructionPolicyActivationEvent,
+  WorkspaceInstructionPolicyActivationResponse,
+  WorkspaceInstructionPolicyActivationType,
+  WorkspaceInstructionPolicyConflictResponse,
+  WorkspaceInstructionPolicyDiffRequest,
+  WorkspaceInstructionPolicyDiffResponse,
+  WorkspaceInstructionPolicyDraftProvenanceSource,
+  WorkspaceInstructionPolicyHead,
+  WorkspaceInstructionPolicyKind,
+  WorkspaceInstructionPolicyListOptions,
+  WorkspaceInstructionPolicyListResponse,
+  WorkspaceInstructionPolicyProvenanceSource,
+  WorkspaceInstructionPolicyRevision,
+  WorkspaceInstructionPolicyRevisionIdentity,
+  WorkspaceInstructionPolicyScope,
+  WorkspaceInstructionPolicyTarget,
+} from "./workspace-instruction-policies";
 export {
   DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
   authorizeTranscriptionAdapter,
@@ -86,6 +109,7 @@ export {
   KNOWN_USAGE_EVENT_TYPES,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
   SESSION_EVENT_TYPES,
@@ -167,6 +191,7 @@ export type {
   CreateApiKeyRequest,
   CreateApiKeyResponse,
   CreateCapabilityCatalogItemRequest,
+  ConnectOpenGeniSlackBotRequest,
   CreateConnectionRequest,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
@@ -175,6 +200,7 @@ export type {
   CreateFileUploadResponse,
   CreateGitHubAppManifestRequest,
   CreateGitHubAppManifestResponse,
+  CreateKnowledgeDropRequest,
   CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
@@ -184,11 +210,15 @@ export type {
   DiscoverMcpCapabilitiesResponse,
   Document,
   DocumentBase,
+  DocumentCuration,
+  DocumentCurationStatus,
   DocumentSearchMode,
   DocumentSearchRequest,
   DocumentSearchResponse,
   DocumentSearchResult,
   DocumentStatus,
+  DocumentVisibility,
+  MoveDocumentRequest,
   EnableCapabilityRequest,
   EnablePackRequest,
   Entitlements,
@@ -206,7 +236,9 @@ export type {
   FileUploadData,
   GetPackResponse,
   GitHubAppInfo,
+  GitHubBindingStatus,
   GitHubInstallationBinding,
+  GitHubInstallationLifecycle,
   GitHubRepositoriesResponse,
   GitHubRepository,
   GitHubRepositoryScope,
@@ -411,6 +443,7 @@ export type {
   UpdateSessionMcpApprovalPolicyResponse,
   UpdateSessionPinRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
   UpdateWorkspaceEnvironmentRequest,
   UpdateWorkspaceMemberRequest,

package/src/types.ts

@@ -276,6 +276,18 @@ export type SessionToolPolicy = {
   inheritedFromSessionId: string | null;
 };
 
+export type UpdateSessionToolPolicyRequest =
+  | {
+      mode: "workspace_default";
+      expectedVersion: number;
+    }
+  | {
+      /** Omitted for compatibility with the original explicit-only API. */
+      mode?: "explicit" | undefined;
+      tools: ToolRef[];
+      expectedVersion: number;
+    };
+
 export type SessionEffectiveToolPolicy = {
   mode: SessionToolPolicy["mode"];
   inheritedFromSessionId: string | null;
@@ -377,6 +389,8 @@ export type ConnectionMetadata = {
   lastUsedAt: string | null;
   lastError: string | null;
   version: number;
+  verifiedInstallAt?: string | null;
+  verifiedInstallVersion?: number | null;
   metadata: Record<string, unknown>;
   createdBySubjectId: string | null;
   updatedBySubjectId: string | null;
@@ -394,6 +408,13 @@ export type CreateConnectionRequest = {
   metadata?: Record<string, unknown> | undefined;
 };
 
+export type ConnectOpenGeniSlackBotRequest = {
+  /** Write-only Slack bot token. It is never returned by the API. */
+  token: string;
+  /** Existing OpenGeni Slack bot connection to reinstall in place. */
+  connectionId?: string | undefined;
+};
+
 export type UpdateConnectionRequest = {
   providerDomain?: string | undefined;
   subjectId?: string | null | undefined;
@@ -472,6 +493,7 @@ export type Session = {
   resources: ResourceRef[];
   tools: ToolRef[];
   toolPolicy?: SessionToolPolicy | undefined;
+  toolPolicyVersion?: number | undefined;
   effectiveToolPolicy?: SessionEffectiveToolPolicy | undefined;
   metadata: Record<string, unknown>;
   /** Frozen creator fact; later turns carry their own independent initiator. */
@@ -762,6 +784,7 @@ export const SESSION_EVENT_TYPES = [
   "terminal.pty.exited",
   "session.title_set",
   "session.mcp.approval_policy.updated",
+  "session.tool_policy.updated",
   // Multi-account Codex (P1): the session's inference account changed.
   "codex.account.switched",
   // credential allocator metadata-only per-turn credential selection audit.
@@ -1492,6 +1515,7 @@ export type ScheduledTaskAgentConfig = {
   resources: ResourceRef[];
   tools: ToolRef[];
   metadata: Record<string, unknown>;
+  slackBotConnectionId?: string | undefined;
   model?: string | undefined;
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
@@ -1993,6 +2017,8 @@ export type ClientAuthConfig =
 // parity suite. The SDK has no runtime dependency on the Zod contracts package.
 export const OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+/** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
+export const OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id" as const;
 
 /**
  * Public, unauthenticated-by-default client bootstrap config returned by
@@ -2324,6 +2350,8 @@ export type NewSessionDraft = {
   text: string;
   resources: ResourceRef[];
   tools: ToolRef[];
+  /** False inherits the workspace-default MCP policy; true preserves an explicit array. */
+  toolsProvided: boolean;
   model: string;
   reasoningEffort: ReasoningEffort;
   options: NewSessionDraftOptions;
@@ -2470,6 +2498,7 @@ export type ScheduledTaskAgentConfigInput = {
   resources?: ResourceRef[] | undefined;
   tools?: ToolRef[] | undefined;
   metadata?: Record<string, unknown> | undefined;
+  slackBotConnectionId?: string | undefined;
   model?: string | undefined;
   reasoningEffort?: ReasoningEffort | undefined;
   sandboxBackend?: SandboxBackend | undefined;
@@ -2823,6 +2852,19 @@ export type KnowledgeSourceKind =
   | "other";
 export type DocumentSearchMode = "hybrid" | "vector" | "keyword";
 
+export type DocumentVisibility = "workspace" | "private";
+
+export type DocumentCurationStatus = "none" | "pending" | "suggested" | "auto_filed" | "failed";
+
+export type DocumentCuration = {
+  suggestedBaseId: string | null;
+  suggestedBaseName: string | null;
+  confidence: number;
+  reason: string | null;
+  originalTitle: string | null;
+  model: string | null;
+};
+
 export type DocumentBase = {
   id: string;
   workspaceId: string;
@@ -2851,6 +2893,13 @@ export type Document = {
   sourceUpdatedAt: string | null;
   sourceVersion: string | null;
   aclTags: string[];
+  visibility: DocumentVisibility;
+  createdBy: string | null;
+  agentAccess: boolean;
+  summary: string | null;
+  topics: string[];
+  curationStatus: DocumentCurationStatus;
+  curation: DocumentCuration | null;
   createdAt: string;
   updatedAt: string;
 };
@@ -2897,6 +2946,21 @@ export type AddDocumentRequest = {
   sourceUpdatedAt?: string | undefined;
   sourceVersion?: string | undefined;
   aclTags?: string[] | undefined;
+  visibility?: DocumentVisibility | undefined;
+  agentAccess?: boolean | undefined;
+};
+
+export type CreateKnowledgeDropRequest = {
+  text?: string | undefined;
+  fileId?: string | undefined;
+  filename?: string | undefined;
+  title?: string | undefined;
+  visibility?: DocumentVisibility | undefined;
+  agentAccess?: boolean | undefined;
+};
+
+export type MoveDocumentRequest = {
+  targetBaseId?: string | undefined;
 };
 
 export type DocumentSearchRequest = {
@@ -3333,10 +3397,16 @@ export type GitHubRepository = {
 
 export type GitHubRepositoryScope = "all" | "selected";
 
+export type GitHubBindingStatus = "disabled" | "unbound" | "bound";
+
+export type GitHubInstallationLifecycle = "active" | "suspended" | "deleted" | "unverified";
+
 export type GitHubInstallationBinding = {
   installationId: number;
+  githubAccountId: number | null;
   accountLogin: string | null;
   accountType: string | null;
+  lifecycle: GitHubInstallationLifecycle;
   repositoryScope: GitHubRepositoryScope;
   repositoryCount: number;
   createdAt: string;
@@ -3345,12 +3415,14 @@ export type GitHubInstallationBinding = {
 
 export type GitHubAppInfo = {
   configured: boolean;
+  /** Truthful workspace binding state; server App credentials alone are not a binding. */
+  status: GitHubBindingStatus;
   appId: string | null;
   clientId: string | null;
   appSlug: string | null;
-  /** Reserved compatibility field; null while new installation binding is disabled. */
+  /** Fresh GitHub-controlled installation/configuration consent entry point. */
   installUrl: string | null;
-  /** Reserved compatibility field; null while new installation binding is disabled. */
+  /** Compatibility alias for installUrl; no repository-admin chooser is exposed. */
   linkUrl: string | null;
   /** Installation bindings owned independently by this workspace. */
   installations: GitHubInstallationBinding[];

package/src/workspace-instruction-policies.ts

@@ -0,0 +1,124 @@
+export type WorkspaceInstructionPolicyKind = "charter" | "policy";
+export type WorkspaceInstructionPolicyScope = "global" | "role";
+export type WorkspaceInstructionPolicyProvenanceSource =
+  | "human"
+  | "onboarding"
+  | "knowledge_proposal"
+  | "legacy_import";
+export type WorkspaceInstructionPolicyDraftProvenanceSource = Exclude<
+  WorkspaceInstructionPolicyProvenanceSource,
+  "legacy_import"
+>;
+export type WorkspaceInstructionPolicyActivationType = "activate" | "rollback";
+
+export function normalizeWorkspaceInstructionPolicyRoleKey(value: string): string {
+  return value.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, "-").replace(/-+/g, "-");
+}
+
+export type WorkspaceInstructionPolicyTarget = {
+  kind: WorkspaceInstructionPolicyKind;
+  scope: WorkspaceInstructionPolicyScope;
+  roleKey: string | null;
+};
+
+export type WorkspaceInstructionPolicyRevisionIdentity = {
+  id: string;
+  revision: number;
+  contentHash: string;
+};
+
+export type WorkspaceInstructionPolicyRevision = WorkspaceInstructionPolicyRevisionIdentity &
+  WorkspaceInstructionPolicyTarget & {
+    accountId: string;
+    workspaceId: string;
+    content: string;
+    provenance: {
+      source: WorkspaceInstructionPolicyProvenanceSource;
+      sourceId: string | null;
+    };
+    supersedesRevisionId: string | null;
+    createdBySubjectId: string;
+    createdAt: string;
+  };
+
+export type WorkspaceInstructionPolicyHead = WorkspaceInstructionPolicyTarget & {
+  workspaceId: string;
+  revisionId: string;
+  revision: number;
+  contentHash: string;
+  activationVersion: number;
+  activatedAt: string;
+};
+
+export type WorkspaceInstructionPolicyActivationEvent = WorkspaceInstructionPolicyTarget & {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  type: WorkspaceInstructionPolicyActivationType;
+  activationVersion: number;
+  oldRevision: WorkspaceInstructionPolicyRevisionIdentity | null;
+  newRevision: WorkspaceInstructionPolicyRevisionIdentity;
+  actorSubjectId: string;
+  reason: string;
+  createdAt: string;
+};
+
+export type CreateWorkspaceInstructionPolicyDraftRequest = WorkspaceInstructionPolicyTarget & {
+  content: string;
+  provenanceSource?: WorkspaceInstructionPolicyDraftProvenanceSource;
+  provenanceSourceId?: string | null;
+  supersedesRevisionId?: string | null;
+};
+
+export type ImportLegacyWorkspaceInstructionPolicyDraftRequest = {
+  supersedesRevisionId?: string | null;
+};
+
+export type WorkspaceInstructionPolicyListOptions = {
+  kind?: WorkspaceInstructionPolicyKind;
+  scope?: WorkspaceInstructionPolicyScope;
+  roleKey?: string;
+  afterRevision?: number;
+  limit?: number;
+};
+
+export type WorkspaceInstructionPolicyListResponse = {
+  revisions: WorkspaceInstructionPolicyRevision[];
+  activeHeads: WorkspaceInstructionPolicyHead[];
+  activationEvents: WorkspaceInstructionPolicyActivationEvent[];
+  nextAfterRevision: number | null;
+};
+
+export type WorkspaceInstructionPolicyDiffRequest = {
+  fromRevisionId: string;
+  toRevisionId: string;
+};
+
+export type WorkspaceInstructionPolicyDiffResponse = {
+  from: WorkspaceInstructionPolicyRevision;
+  to: WorkspaceInstructionPolicyRevision;
+  format: "unified";
+  diff: string;
+};
+
+export type ActivateWorkspaceInstructionPolicyRequest = {
+  expectedCurrentRevisionId: string | null;
+  reason: string;
+};
+
+export type RollbackWorkspaceInstructionPolicyRequest = {
+  targetRevisionId: string;
+  expectedCurrentRevisionId: string;
+  reason: string;
+};
+
+export type WorkspaceInstructionPolicyActivationResponse = {
+  head: WorkspaceInstructionPolicyHead;
+  event: WorkspaceInstructionPolicyActivationEvent;
+};
+
+export type WorkspaceInstructionPolicyConflictResponse = {
+  code: "WORKSPACE_INSTRUCTION_POLICY_CONFLICT";
+  message: string;
+  currentHead: WorkspaceInstructionPolicyHead | null;
+};