@opengeni/contracts 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -478,8 +478,10 @@ export type ErrorCode = z.infer<typeof ErrorCode>;
 
 export const ErrorEnvelope = z.object({
   error: z.object({
+    status: z.number().int().min(400).max(599),
     code: ErrorCode,
     message: z.string(),
+    retryable: z.boolean(),
     requestId: z.string().optional(),
     details: z.record(z.string(), z.unknown()).optional(),
   }),
@@ -2176,11 +2178,22 @@ export type ConnectionCredentialsPort = {
 
 export type GitHubInstallationSummary = {
   installationId: number;
+  accountId: number;
   accountLogin: string | null;
   accountType: string | null;
   suspended: boolean;
 };
 
+export type GitHubInstallationAuthorityKind = "personal_owner" | "organization_owner";
+
+export interface GitHubInstallationBindingProof {
+  actorId: number;
+  actorLogin: string;
+  authorityKind: GitHubInstallationAuthorityKind;
+  installation: GitHubInstallationSummary;
+  repositories: GitHubRepository[];
+}
+
 export type GitHubRepositoryPermissions = {
   admin: boolean;
   maintain: boolean;
@@ -2198,6 +2211,18 @@ export type GitHubUserInstallationAccess = GitHubInstallationSummary & {
 };
 
 export type GitHubAppApiPort = {
+  /**
+   * Exchange one fresh GitHub user-authorization code and prove current
+   * installation authority. Implementations must accept only exact personal
+   * ownership or active organization ownership; installation visibility,
+   * repository permission bits, and App Manager metadata are not authority.
+   * Organization ownership must be revalidated after repository discovery,
+   * immediately before returning the proof used by the durable bind.
+   */
+  authorizeInstallationBinding?: (input: {
+    code: string;
+    installationId: number;
+  }) => Promise<GitHubInstallationBindingProof>;
   authorizeUser?: (input: { code: string }) => Promise<GitHubUserInstallationAccess[]>;
   verifyInstallationAccessForUser?: (input: {
     code: string;
@@ -2491,6 +2516,37 @@ export type KnowledgeSourceKind = z.infer<typeof KnowledgeSourceKind>;
 export const DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
 export type DocumentSearchMode = z.infer<typeof DocumentSearchMode>;
 
+// 'workspace' documents are readable by anyone with workspace access;
+// 'private' documents are readable only by the grant subject that created them.
+export const DocumentVisibility = z.enum(["workspace", "private"]);
+export type DocumentVisibility = z.infer<typeof DocumentVisibility>;
+
+// Knowledge-drop auto-curation lifecycle. 'none' = ordinary caller-described add
+// (never auto-curated). 'pending' = dropped, curation runs during indexing.
+// 'suggested' = curated but the base move was NOT applied (low confidence or
+// conflict) — the suggestion lives in Document.curation. 'auto_filed' = curated
+// and moved into the suggested base. 'failed' = curation errored (fail-soft;
+// the document still indexes and stays searchable).
+export const DocumentCurationStatus = z.enum([
+  "none",
+  "pending",
+  "suggested",
+  "auto_filed",
+  "failed",
+]);
+export type DocumentCurationStatus = z.infer<typeof DocumentCurationStatus>;
+
+// Curator audit blob persisted on the document.
+export const DocumentCuration = z.object({
+  suggestedBaseId: z.string().uuid().nullable(),
+  suggestedBaseName: z.string().nullable(),
+  confidence: z.number().min(0).max(1),
+  reason: z.string().nullable(),
+  originalTitle: z.string().nullable(),
+  model: z.string().nullable(),
+});
+export type DocumentCuration = z.infer<typeof DocumentCuration>;
+
 export const DocumentBase = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
@@ -2520,6 +2576,13 @@ export const Document = z.object({
   sourceUpdatedAt: z.string().nullable(),
   sourceVersion: z.string().nullable(),
   aclTags: z.array(z.string()),
+  visibility: DocumentVisibility,
+  createdBy: z.string().nullable(),
+  agentAccess: z.boolean(),
+  summary: z.string().nullable(),
+  topics: z.array(z.string()),
+  curationStatus: DocumentCurationStatus,
+  curation: DocumentCuration.nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -2569,9 +2632,37 @@ export const AddDocumentRequest = z.object({
   sourceUpdatedAt: z.string().datetime({ offset: true }).optional(),
   sourceVersion: z.string().min(1).optional(),
   aclTags: z.array(z.string().min(1)).optional(),
+  visibility: DocumentVisibility.optional(),
+  agentAccess: z.boolean().optional(),
 });
 export type AddDocumentRequest = z.infer<typeof AddDocumentRequest>;
 
+// A knowledge drop: raw text or an already-uploaded file, with no required
+// metadata. The server files it into the workspace Default base. When a
+// curation provider is enabled, it may name, summarize, categorize, and
+// (confidence permitting) move the document; provider=none leaves caller
+// metadata and Default placement unchanged.
+export const CreateKnowledgeDropRequest = z
+  .object({
+    text: z.string().min(1).max(2_000_000).optional(),
+    fileId: z.string().uuid().optional(),
+    filename: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    visibility: DocumentVisibility.optional(),
+    agentAccess: z.boolean().optional(),
+  })
+  .refine((value) => (value.text === undefined) !== (value.fileId === undefined), {
+    message: "provide exactly one of text or fileId",
+  });
+export type CreateKnowledgeDropRequest = z.infer<typeof CreateKnowledgeDropRequest>;
+
+// Move a document (and its indexed chunks) to another base. With no explicit
+// targetBaseId, applies the document's stored curation suggestion.
+export const MoveDocumentRequest = z.object({
+  targetBaseId: z.string().uuid().optional(),
+});
+export type MoveDocumentRequest = z.infer<typeof MoveDocumentRequest>;
+
 export const DocumentSearchRequest = z.object({
   query: z.string().min(1),
   baseIds: z.array(z.string().uuid()).optional(),
@@ -3134,6 +3225,29 @@ export const UpdateSessionRequest = z.object({
 });
 export type UpdateSessionRequest = z.infer<typeof UpdateSessionRequest>;
 
+/**
+ * Replace an existing session's durable tool policy, or explicitly opt back in
+ * to the current workspace defaults. The mode-less explicit shape is retained
+ * for compatibility with clients released before workspace-default adoption
+ * was supported.
+ */
+export const UpdateSessionToolPolicyRequest = z.union([
+  z
+    .object({
+      mode: z.literal("workspace_default"),
+      expectedVersion: z.number().int().positive(),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("explicit").optional(),
+      tools: z.array(ToolRef).max(64),
+      expectedVersion: z.number().int().positive(),
+    })
+    .strict(),
+]);
+export type UpdateSessionToolPolicyRequest = z.infer<typeof UpdateSessionToolPolicyRequest>;
+
 /**
  * A member's personal pin preference for a session. `expectedVersion` is
  * optional: ordinary pin/unpin actions are idempotent last-write-wins, while a
@@ -3275,6 +3389,7 @@ export const SessionAuthorizationOperation = z.enum([
   "session.human_input.write",
   "session.title.write",
   "session.mcp.approval_policy.write",
+  "session.tool_policy.write",
   "session.goal.read",
   "session.goal.write",
   "session.child.create",
@@ -3569,6 +3684,8 @@ export const NewSessionDraft = z.object({
   text: z.string(),
   resources: z.array(ResourceRef),
   tools: z.array(ToolRef),
+  /** False means the workspace-default MCP policy is still inherited. */
+  toolsProvided: z.boolean().default(false),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
   options: NewSessionDraftOptions,
@@ -3580,6 +3697,7 @@ export const SaveNewSessionDraftRequest = NewSessionDraft.pick({
   text: true,
   resources: true,
   tools: true,
+  toolsProvided: true,
   model: true,
   reasoningEffort: true,
   options: true,
@@ -4155,6 +4273,10 @@ export const ScheduledTaskAgentConfig = z.object({
   resources: z.array(ResourceRef).default([]),
   tools: z.array(ToolRef).default([]),
   metadata: z.record(z.string(), z.unknown()).default({}),
+  // Explicit workspace-shared OpenGeni Slack bot binding for scheduled runs.
+  // The worker copies this non-secret pointer into session metadata; the
+  // first-party Slack tools never fall back to a personal hosted-MCP grant.
+  slackBotConnectionId: z.string().uuid().optional(),
   model: z.string().min(1).optional(),
   reasoningEffort: ReasoningEffort.optional(),
   sandboxBackend: SandboxBackend.optional(),
@@ -4539,6 +4661,34 @@ 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 OPENGENI_SLACK_BOT_CREDENTIAL_ROLE = "opengeni_slack_bot" as const;
+export const OPENGENI_SLACK_BOT_CREDENTIAL_LABEL = "OpenGeni Slack bot" as const;
+export const OPENGENI_SLACK_BOT_SESSION_METADATA_KEY = "opengeniSlackBotConnectionId" as const;
+export const OPENGENI_SLACK_BOT_REQUIRED_SCOPES = [
+  "chat:write",
+  "im:write",
+  "channels:read",
+  "channels:history",
+  "groups:read",
+  "groups:history",
+  "users:read",
+] as const;
+export const OPENGENI_SLACK_BOT_FORBIDDEN_SCOPES = ["channels:join", "chat:write.public"] as const;
+
+export const OpenGeniSlackBotConnectionMetadata = z
+  .object({
+    credentialRole: z.literal(OPENGENI_SLACK_BOT_CREDENTIAL_ROLE),
+    credentialLabel: z.literal(OPENGENI_SLACK_BOT_CREDENTIAL_LABEL),
+    slackTeamId: z.string().min(1).max(64),
+    slackTeamName: z.string().min(1).max(256),
+    botUserId: z.string().min(1).max(64),
+    botId: z.string().min(1).max(64),
+    botDisplayName: z.literal("OpenGeni"),
+    verifiedAt: z.string().datetime({ offset: true }),
+  })
+  .passthrough();
+export type OpenGeniSlackBotConnectionMetadata = z.infer<typeof OpenGeniSlackBotConnectionMetadata>;
+
 export const ConnectionMetadata = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -4553,6 +4703,8 @@ export const ConnectionMetadata = z.object({
   lastUsedAt: z.string().nullable(),
   lastError: z.string().nullable(),
   version: z.number().int().positive(),
+  verifiedInstallAt: z.string().datetime({ offset: true }).nullable().optional(),
+  verifiedInstallVersion: z.number().int().positive().nullable().optional(),
   metadata: z.record(z.string(), z.unknown()),
   createdBySubjectId: z.string().nullable(),
   updatedBySubjectId: z.string().nullable(),
@@ -4575,6 +4727,16 @@ export const CreateConnectionRequest = z.object({
 });
 export type CreateConnectionRequest = z.infer<typeof CreateConnectionRequest>;
 
+/**
+ * Write-only Slack bot installation input. `token` is accepted only by the
+ * dedicated validated endpoint and is never represented in a response schema.
+ */
+export const ConnectOpenGeniSlackBotRequest = z.object({
+  token: z.string().trim().startsWith("xoxb-").max(8192),
+  connectionId: z.string().uuid().optional(),
+});
+export type ConnectOpenGeniSlackBotRequest = z.infer<typeof ConnectOpenGeniSlackBotRequest>;
+
 export const UpdateConnectionRequest = z.object({
   providerDomain: z.string().min(1).optional(),
   subjectId: z.string().min(1).nullable().optional(),
@@ -4853,6 +5015,10 @@ export const Session = z.object({
   // Origin of the persisted tool allow-list. Optional for rolling client
   // compatibility; current servers emit it and legacy rows map to `legacy`.
   toolPolicy: SessionToolPolicy.optional(),
+  // Optimistic-concurrency fence for durable policy mutations. Optional for
+  // older clients/fixtures; current servers always emit the authoritative
+  // value.
+  toolPolicyVersion: z.number().int().positive().optional(),
   // Secret-safe current resolution, computed at an API/read or execution
   // boundary from IDs only. Optional because internal DB readers need not load
   // the workspace runtime registry.
@@ -5103,6 +5269,7 @@ export const SessionEventType = z.enum([
   "terminal.pty.exited", // PTY session ended (exitCode/reason)
   "session.title_set",
   "session.mcp.approval_policy.updated",
+  "session.tool_policy.updated",
   // Multi-account Codex (P1): the account a session's turn runs on changed
   // (manual switch in P1; failover/rotation in P3 reuse the same event). Drives
   // the in-session "Running on:" indicator's live flip.
@@ -5268,6 +5435,7 @@ export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
     "session.queue.changed",
     "session.queue.prompt.cancelled",
     "session.mcp.approval_policy.updated",
+    "session.tool_policy.updated",
   ],
   terminal: [
     "turn.completed",
@@ -7468,10 +7636,18 @@ export type GitHubRepository = z.infer<typeof GitHubRepository>;
 export const GitHubRepositoryScope = z.enum(["all", "selected"]);
 export type GitHubRepositoryScope = z.infer<typeof GitHubRepositoryScope>;
 
+export const GitHubBindingStatus = z.enum(["disabled", "unbound", "bound"]);
+export type GitHubBindingStatus = z.infer<typeof GitHubBindingStatus>;
+
+export const GitHubInstallationLifecycle = z.enum(["active", "suspended", "deleted", "unverified"]);
+export type GitHubInstallationLifecycle = z.infer<typeof GitHubInstallationLifecycle>;
+
 export const GitHubInstallationBinding = z.object({
   installationId: z.number().int().positive(),
+  githubAccountId: z.number().int().positive().nullable(),
   accountLogin: z.string().nullable(),
   accountType: z.string().nullable(),
+  lifecycle: GitHubInstallationLifecycle,
   repositoryScope: GitHubRepositoryScope,
   repositoryCount: z.number().int().nonnegative(),
   createdAt: z.string(),
@@ -7481,6 +7657,7 @@ export type GitHubInstallationBinding = z.infer<typeof GitHubInstallationBinding
 
 export const GitHubAppInfo = z.object({
   configured: z.boolean(),
+  status: GitHubBindingStatus,
   appId: z.string().nullable(),
   clientId: z.string().nullable(),
   appSlug: z.string().nullable(),
@@ -8473,6 +8650,8 @@ export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalog
  */
 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;
 
 export const ClientConfig = /* @__PURE__ */ defineModelContractSchema(() =>
   z.object({
@@ -8594,3 +8773,5 @@ export function evaluateWorkspaceModelPolicy(
 }
 
 export * from "./codex-fleet-policy";
+export * from "./secret-redaction";
+export * from "./workspace-instruction-policies";