@opengeni/contracts 0.6.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,13 +32,10 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsup"
+    "build": "tsup",
+    "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
     "zod": "^4.2.1"
-  },
-  "devDependencies": {
-    "tsup": "^8.5.0",
-    "typescript": "^6.0.3"
   }
 }

package/src/index.ts

@@ -429,20 +429,6 @@ export const ErrorEnvelope = z.object({
 });
 export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
 
-export const PageInfo = z.object({
-  limit: z.number().int().positive(),
-  nextCursor: z.string().nullable(),
-  hasMore: z.boolean(),
-});
-export type PageInfo = z.infer<typeof PageInfo>;
-
-export function paginated<T extends z.ZodTypeAny>(item: T) {
-  return z.object({
-    data: z.array(item),
-    page: PageInfo,
-  });
-}
-
 export const Permission = z.enum([
   "account:read",
   "account:admin",
@@ -484,12 +470,18 @@ export const Permission = z.enum([
   "github:manage",
   "github:use",
   "api_keys:manage",
+  "connections:read",
+  "connections:write",
   "environments:manage",
   "environments:use",
   // Attach or rotate per-session third-party MCP server credentials. Deliberately
   // not part of the worker's default first-party MCP permission set: a sandboxed
   // agent must not be able to hand itself new bearer credentials.
   "mcp_servers:attach",
+  // Programmatic sandbox -> tool access through the first-party MCP gate. This is
+  // intentionally narrow and is never part of first-party MCP defaults; callers
+  // must receive it through an explicit delegated `ogd_` mint carrying sessionId.
+  "toolspace:call",
   "goals:manage",
   // Bring-your-own-compute (M5). enrollments:read lists a workspace's machines;
   // enrollments:manage approves a device-flow enrollment (the LOUD whole-machine
@@ -501,6 +493,10 @@ export const Permission = z.enum([
 ]);
 export type Permission = z.infer<typeof Permission>;
 
+export function prefixedMcpToolName(registryId: string, toolName: string): string {
+  return `${registryId}__${toolName}`;
+}
+
 export const ProductAccessMode = z.enum(["local", "configured", "managed"]);
 export type ProductAccessMode = z.infer<typeof ProductAccessMode>;
 
@@ -1296,6 +1292,12 @@ export type FileDownloadUrlResponse = z.infer<typeof FileDownloadUrlResponse>;
 export const DocumentStatus = z.enum(["queued", "indexing", "ready", "failed"]);
 export type DocumentStatus = z.infer<typeof DocumentStatus>;
 
+export const KnowledgeSourceKind = z.enum(["manual_upload", "meeting_transcript", "repository", "email", "chat", "document", "web", "other"]);
+export type KnowledgeSourceKind = z.infer<typeof KnowledgeSourceKind>;
+
+export const DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
+export type DocumentSearchMode = z.infer<typeof DocumentSearchMode>;
+
 export const DocumentBase = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -1316,6 +1318,15 @@ export const Document = z.object({
   parser: z.string(),
   chunkCount: z.number().int().nonnegative(),
   error: z.string().nullable(),
+  sourceKind: KnowledgeSourceKind,
+  sourceUri: z.string().nullable(),
+  sourceExternalId: z.string().nullable(),
+  sourceTitle: z.string().nullable(),
+  sourceAuthor: z.string().nullable(),
+  sourceCreatedAt: z.string().nullable(),
+  sourceUpdatedAt: z.string().nullable(),
+  sourceVersion: z.string().nullable(),
+  aclTags: z.array(z.string()),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -1330,8 +1341,20 @@ export const DocumentSearchResult = z.object({
   title: z.string(),
   text: z.string(),
   score: z.number(),
+  matchType: DocumentSearchMode,
+  vectorScore: z.number().nullable(),
+  keywordScore: z.number().nullable(),
   chunkIndex: z.number().int().nonnegative(),
   metadata: z.record(z.string(), z.unknown()),
+  sourceKind: KnowledgeSourceKind,
+  sourceUri: z.string().nullable(),
+  sourceExternalId: z.string().nullable(),
+  sourceTitle: z.string().nullable(),
+  sourceAuthor: z.string().nullable(),
+  sourceCreatedAt: z.string().nullable(),
+  sourceUpdatedAt: z.string().nullable(),
+  sourceVersion: z.string().nullable(),
+  aclTags: z.array(z.string()),
 });
 export type DocumentSearchResult = z.infer<typeof DocumentSearchResult>;
 
@@ -1343,15 +1366,95 @@ export type CreateDocumentBaseRequest = z.infer<typeof CreateDocumentBaseRequest
 
 export const AddDocumentRequest = z.object({
   fileId: z.string().uuid(),
+  title: z.string().min(1).optional(),
+  sourceKind: KnowledgeSourceKind.optional(),
+  sourceUri: z.string().min(1).optional(),
+  sourceExternalId: z.string().min(1).optional(),
+  sourceTitle: z.string().min(1).optional(),
+  sourceAuthor: z.string().min(1).optional(),
+  sourceCreatedAt: z.string().datetime({ offset: true }).optional(),
+  sourceUpdatedAt: z.string().datetime({ offset: true }).optional(),
+  sourceVersion: z.string().min(1).optional(),
+  aclTags: z.array(z.string().min(1)).optional(),
 });
 export type AddDocumentRequest = z.infer<typeof AddDocumentRequest>;
 
 export const DocumentSearchRequest = z.object({
   query: z.string().min(1),
-  limit: z.number().int().positive().max(20).default(5),
+  baseIds: z.array(z.string().uuid()).optional(),
+  mode: DocumentSearchMode.optional(),
+  sourceKinds: z.array(KnowledgeSourceKind).optional(),
+  aclTags: z.array(z.string().min(1)).optional(),
+  limit: z.number().int().positive().max(50).default(5),
 });
 export type DocumentSearchRequest = z.infer<typeof DocumentSearchRequest>;
 
+export const KnowledgeMemoryStatus = z.enum(["proposed", "approved", "rejected"]);
+export type KnowledgeMemoryStatus = z.infer<typeof KnowledgeMemoryStatus>;
+
+export const KnowledgeMemoryKind = z.enum(["semantic", "episodic", "procedural", "decision", "preference"]);
+export type KnowledgeMemoryKind = z.infer<typeof KnowledgeMemoryKind>;
+
+export const KnowledgeSourceRef = z.object({
+  kind: z.enum(["document_chunk", "document", "session_event", "memory", "external"]),
+  id: z.string().min(1),
+  uri: z.string().min(1).optional(),
+  title: z.string().min(1).optional(),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type KnowledgeSourceRef = z.infer<typeof KnowledgeSourceRef>;
+
+export const KnowledgeMemory = z.object({
+  id: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  status: KnowledgeMemoryStatus,
+  kind: KnowledgeMemoryKind,
+  scope: z.string(),
+  text: z.string(),
+  sourceRefs: z.array(KnowledgeSourceRef),
+  confidence: z.number().min(0).max(1),
+  metadata: z.record(z.string(), z.unknown()),
+  createdBySessionId: z.string().uuid().nullable(),
+  reviewedBy: z.string().nullable(),
+  reviewedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type KnowledgeMemory = z.infer<typeof KnowledgeMemory>;
+
+export const CreateKnowledgeMemoryRequest = z.object({
+  status: KnowledgeMemoryStatus.default("proposed"),
+  kind: KnowledgeMemoryKind.default("semantic"),
+  scope: z.string().min(1).default("workspace"),
+  text: z.string().min(1),
+  sourceRefs: z.array(KnowledgeSourceRef).default([]),
+  confidence: z.number().min(0).max(1).default(0.5),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+  createdBySessionId: z.string().uuid().optional(),
+});
+export type CreateKnowledgeMemoryRequest = z.infer<typeof CreateKnowledgeMemoryRequest>;
+
+export const UpdateKnowledgeMemoryRequest = z.object({
+  status: KnowledgeMemoryStatus.optional(),
+  kind: KnowledgeMemoryKind.optional(),
+  scope: z.string().min(1).optional(),
+  text: z.string().min(1).optional(),
+  sourceRefs: z.array(KnowledgeSourceRef).optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  reviewedBy: z.string().min(1).optional(),
+});
+export type UpdateKnowledgeMemoryRequest = z.infer<typeof UpdateKnowledgeMemoryRequest>;
+
+export const KnowledgeMemorySearchRequest = z.object({
+  query: z.string().min(1).optional(),
+  status: KnowledgeMemoryStatus.optional(),
+  kind: KnowledgeMemoryKind.optional(),
+  scope: z.string().min(1).optional(),
+  limit: z.number().int().positive().max(100).default(20),
+});
+export type KnowledgeMemorySearchRequest = z.infer<typeof KnowledgeMemorySearchRequest>;
+
 export const ToolRef = z.object({
   kind: z.literal("mcp"),
   id: z.string().min(1),
@@ -1381,6 +1484,12 @@ export const SessionMcpServerInput = z.object({
   allowedTools: z.array(z.string().min(1)).optional(),
   timeoutMs: z.number().int().positive().optional(),
   cacheToolsList: z.boolean().optional(),
+  // Human-approval policy for this server's tools. `true` = every tool of this
+  // server requires approval before it runs (a `session.requiresAction` pause
+  // the caller resolves with `user.approvalDecision`); a string[] = ONLY the
+  // listed UNPREFIXED tool names require approval (e.g. reads auto-run, writes
+  // ask); absent / `false` = auto-run everything (the historical default).
+  requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
   // Write-only credential headers. Values are encrypted at rest and never
   // returned in session responses or events; response metadata exposes names.
   headers: z.record(z.string(), z.string()).optional(),
@@ -2057,6 +2166,110 @@ export const CreateSocialPostRequest = z.object({
 });
 export type CreateSocialPostRequest = z.infer<typeof CreateSocialPostRequest>;
 
+export const ConnectionKind = z.enum(["oauth2", "api_key", "app_install", "delegated"]);
+export type ConnectionKind = z.infer<typeof ConnectionKind>;
+
+export const ConnectionStatus = z.enum(["active", "needs_reauth", "revoked", "error"]);
+export type ConnectionStatus = z.infer<typeof ConnectionStatus>;
+
+export const McpServerConnectionRef = z.object({
+  connectionId: z.string().uuid().optional(),
+  providerDomain: z.string().min(1),
+  kind: ConnectionKind.optional(),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  subjectScope: z.enum(["workspace", "subject"]).optional(),
+}).strict();
+export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRef>;
+
+export const ConnectionMetadata = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  subjectId: z.string().nullable(),
+  providerDomain: z.string(),
+  kind: ConnectionKind,
+  status: ConnectionStatus,
+  grantedScopes: z.array(z.string()),
+  expiresAt: z.string().nullable(),
+  lastRefreshAt: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+  lastError: z.string().nullable(),
+  version: z.number().int().positive(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdBySubjectId: z.string().nullable(),
+  updatedBySubjectId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type ConnectionMetadata = z.infer<typeof ConnectionMetadata>;
+
+export const ConnectionCredentialBundle = z.record(z.string(), z.unknown());
+export type ConnectionCredentialBundle = z.infer<typeof ConnectionCredentialBundle>;
+
+export const CreateConnectionRequest = z.object({
+  providerDomain: z.string().min(1),
+  kind: ConnectionKind,
+  subjectId: z.string().min(1).nullable().optional(),
+  credential: ConnectionCredentialBundle,
+  grantedScopes: z.array(z.string().min(1)).default([]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+});
+export type CreateConnectionRequest = z.infer<typeof CreateConnectionRequest>;
+
+export const UpdateConnectionRequest = z.object({
+  providerDomain: z.string().min(1).optional(),
+  subjectId: z.string().min(1).nullable().optional(),
+  kind: ConnectionKind.optional(),
+  status: ConnectionStatus.optional(),
+  credential: ConnectionCredentialBundle.optional(),
+  grantedScopes: z.array(z.string().min(1)).optional(),
+  expiresAt: z.string().datetime({ offset: true }).nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type UpdateConnectionRequest = z.infer<typeof UpdateConnectionRequest>;
+
+export const ConnectionResponse = z.object({
+  connection: ConnectionMetadata,
+});
+export type ConnectionResponse = z.infer<typeof ConnectionResponse>;
+
+export const ListConnectionsResponse = z.object({
+  connections: z.array(ConnectionMetadata),
+});
+export type ListConnectionsResponse = z.infer<typeof ListConnectionsResponse>;
+
+export const OAuthStartRequest = z.object({
+  providerDomain: z.string().min(1).optional(),
+  mcpUrl: z.string().url().optional(),
+  resource: z.string().url().optional(),
+  requestedScopes: z.array(z.string().min(1)).default([]),
+  returnPath: z.string().min(1).optional(),
+  connectionId: z.string().uuid().optional(),
+}).refine((value) => Boolean(value.mcpUrl ?? value.resource), {
+  message: "mcpUrl is required",
+  path: ["mcpUrl"],
+});
+export type OAuthStartRequest = z.infer<typeof OAuthStartRequest>;
+
+export const OAuthStartResponse = z.object({
+  state: z.string().min(1),
+  authorizationUrl: z.string().url().nullable(),
+  expiresAt: z.string(),
+});
+export type OAuthStartResponse = z.infer<typeof OAuthStartResponse>;
+
+export const IntegrationClientMetadata = z.object({
+  client_id: z.string().url(),
+  client_name: z.literal("OpenGeni"),
+  redirect_uris: z.array(z.string().url()),
+  token_endpoint_auth_method: z.literal("none"),
+  grant_types: z.array(z.enum(["authorization_code", "refresh_token"])),
+  response_types: z.array(z.literal("code")),
+});
+export type IntegrationClientMetadata = z.infer<typeof IntegrationClientMetadata>;
+
 export const MarketingDailyAnalysisTaskRequest = z.object({
   name: z.string().min(1).optional(),
   connectionIds: z.array(z.string().uuid()).default([]),
@@ -2074,12 +2287,18 @@ export type MarketingDailyAnalysisTaskRequest = z.infer<typeof MarketingDailyAna
 export const CapabilityKind = z.enum(["pack", "mcp", "api", "skill", "plugin"]);
 export type CapabilityKind = z.infer<typeof CapabilityKind>;
 
-export const CapabilitySource = z.enum(["built_in", "configured", "public_registry", "manual"]);
+export const CapabilitySource = z.enum(["built_in", "configured", "public_registry", "registry", "manual"]);
 export type CapabilitySource = z.infer<typeof CapabilitySource>;
 
 export const CapabilityInstallationStatus = z.enum(["active", "disabled"]);
 export type CapabilityInstallationStatus = z.infer<typeof CapabilityInstallationStatus>;
 
+export const CapabilityCatalogAuthKind = z.enum(["oauth2", "api_key", "none", "unknown"]);
+export type CapabilityCatalogAuthKind = z.infer<typeof CapabilityCatalogAuthKind>;
+
+export const CapabilityCatalogTier = z.enum(["verified", "community"]);
+export type CapabilityCatalogTier = z.infer<typeof CapabilityCatalogTier>;
+
 export const CapabilityRuntime = z.object({
   available: z.boolean().default(false),
   mcpServerId: z.string().min(1).optional(),
@@ -2102,6 +2321,18 @@ export const CapabilityCatalogItem = z.object({
   endpointUrl: z.string().url().nullable().default(null),
   installUrl: z.string().url().nullable().default(null),
   authModel: z.string().min(1).nullable().default(null),
+  providerDomain: z.string().min(1).nullable().default(null),
+  surfaceType: z.string().min(1).nullable().default(null),
+  transport: z.string().min(1).nullable().default(null),
+  mcpUrl: z.string().url().nullable().default(null),
+  authKind: CapabilityCatalogAuthKind.nullable().default(null),
+  credentialFacts: z.array(z.record(z.string(), z.unknown())).default([]),
+  tier: CapabilityCatalogTier.nullable().default(null),
+  provenance: z.string().min(1).nullable().default(null),
+  logoAssetPath: z.string().min(1).nullable().default(null),
+  importBatchId: z.string().uuid().nullable().default(null),
+  stale: z.boolean().default(false),
+  staleAt: z.string().nullable().default(null),
   tools: z.array(ToolRef).default([]),
   runtime: CapabilityRuntime.default({ available: false, notes: null }),
   enabled: z.boolean().default(false),
@@ -2145,6 +2376,7 @@ export type CreateCapabilityCatalogItemRequest = z.infer<typeof CreateCapability
 export const EnableCapabilityRequest = z.object({
   config: z.record(z.string(), z.unknown()).default({}),
   metadata: z.record(z.string(), z.unknown()).default({}),
+  connectionRef: McpServerConnectionRef.optional(),
   /**
    * Credential headers for remote MCP capabilities (for example an
    * Authorization bearer token). Values are encrypted at rest with the
@@ -2260,6 +2492,7 @@ export const SessionEventType = z.enum([
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
+  "tool.auth_needed",
   "agent.updated",
   "sandbox.operation.started",
   "sandbox.operation.completed",
@@ -2307,6 +2540,19 @@ export const SessionEventType = z.enum([
 ]);
 export type SessionEventType = z.infer<typeof SessionEventType>;
 
+export const ToolAuthNeededPayload = z.object({
+  serverId: z.string().min(1),
+  toolName: z.string().min(1).nullable().optional(),
+  providerDomain: z.string().min(1),
+  connectionId: z.string().uuid().nullable().optional(),
+  reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  authorizationUrl: z.string().url().optional(),
+  subjectId: z.string().min(1).nullable().optional(),
+});
+export type ToolAuthNeededPayload = z.infer<typeof ToolAuthNeededPayload>;
+
 // Channel-B stream-event payloads (07-channel-b §1.2). SessionEvent.payload is
 // z.unknown() (NOT a discriminated union) — these are standalone schemas parsed
 // explicitly at the producer (the API-direct handshake/rotation) and the SDK/
@@ -3241,6 +3487,11 @@ export const EnrollmentSummary = z.object({
   pubkey: z.string(),
   exposure: z.literal("whole-machine"),
   hasDisplay: z.boolean(),
+  // Present (non-null) only when a display EXISTS but capture is blocked (macOS
+  // Screen Recording / TCC not granted): a human, actionable reason so the UI can
+  // show "display: capture not granted" instead of a bare "headless". null == capture
+  // permitted OR genuinely headless.
+  desktopUnavailableReason: z.string().nullish(),
   allowScreenControl: z.boolean(),
   status: z.enum(["active", "revoked"]),
   os: EnrollmentOs,
@@ -3421,6 +3672,10 @@ export const MachineView = z.object({
   os: z.string(),
   arch: z.string(),
   hasDisplay: z.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: z.string().nullish(),
   allowScreenControl: z.boolean(),
   sharedSessionCount: z.number().int(),
   lastSeenAt: z.string().nullable(),
@@ -3493,6 +3748,10 @@ export type ClientModel = z.infer<typeof ClientModel>;
 
 export const ClientConfig = z.object({
   deploymentRevision: z.string(),
+  // Release-train version of the server (absent on dev/source builds). The
+  // compatibility policy lives in docs/architecture.md — clients within the
+  // same major are supported; evolution is additive within a major.
+  serverVersion: z.string().optional(),
   defaultModel: z.string(),
   allowedModels: z.array(z.string()).min(1),
   // Richer model list (provider-grouped) for the picker. Defaults to [] for