@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/workspace-integrations.ts

@@ -0,0 +1,724 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import {
+  NotificationFact,
+  NotificationLink,
+  NotificationUndeliveredReason,
+  NotificationUrgency,
+  type TurnInitiator,
+  type TurnInitiatorContext,
+} from "./index";
+
+import {
+  OPENGENI_WEBHOOK_TEST_EVENT_TYPE,
+  WORKSPACE_WEBHOOK_EVENT_TYPES,
+} from "./workspace-integration-wire";
+import {
+  UsageAllowancePeriod,
+  UsageAllowanceStatus,
+  UsageAllowanceWindow,
+} from "./usage-allowances";
+
+export * from "./workspace-integration-wire";
+
+/**
+ * Workspace integration primitives for embedding hosts: signed outbound
+ * webhooks and one signed HTTP credential provider per workspace. Both
+ * directions share one signature scheme so a host verifies every Opengeni
+ * request with the same helper.
+ */
+
+export const WorkspaceWebhookEventType = /* @__PURE__ */ defineSchema(() =>
+  z.enum(WORKSPACE_WEBHOOK_EVENT_TYPES),
+);
+export type WorkspaceWebhookEventType = z.infer<typeof WorkspaceWebhookEventType>;
+
+export const WORKSPACE_WEBHOOK_LIMIT_PER_WORKSPACE = 10;
+export const ORGANIZATION_WEBHOOK_LIMIT_PER_ORGANIZATION = 10;
+
+/** Scoping convenience, never authority. Null means all non-personal workspaces. */
+export const IntegrationWorkspaceFilter = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      externalSource: z
+        .string()
+        .min(1)
+        .max(200)
+        .refine(
+          (value) =>
+            !value.includes("\0") &&
+            !/[\uD800-\uDFFF]/u.test(value) &&
+            new TextEncoder().encode(value).byteLength <= 200,
+          "External source must be valid PostgreSQL text of at most 200 UTF-8 bytes",
+        ),
+    })
+    .strict(),
+);
+export type IntegrationWorkspaceFilter = z.infer<typeof IntegrationWorkspaceFilter>;
+
+/** Informational attribution only. It never supplies or changes authorization. */
+export const InitiatingHuman = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    subjectId: z.string(),
+    externalIdentity: z.object({ source: z.string(), externalId: z.string() }).nullable(),
+  }),
+);
+export type InitiatingHuman = z.infer<typeof InitiatingHuman>;
+
+const HttpUrl = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .trim()
+    .min(8)
+    .max(2048)
+    .url()
+    .refine((value) => /^https?:\/\//i.test(value), "URL must use http or https"),
+);
+
+const EventTypes = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(WorkspaceWebhookEventType)
+    .min(1)
+    .max(WORKSPACE_WEBHOOK_EVENT_TYPES.length)
+    .transform((types) => [...new Set(types)]),
+);
+
+export const WorkspaceWebhook = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.string().uuid(),
+      workspaceId: z.string().uuid(),
+      url: z.string(),
+      eventTypes: z.array(WorkspaceWebhookEventType),
+      enabled: z.boolean(),
+      description: z.string().nullable(),
+      createdAt: z.string(),
+      updatedAt: z.string(),
+    })
+    .strict(),
+);
+export type WorkspaceWebhook = z.infer<typeof WorkspaceWebhook>;
+
+export const CreateWorkspaceWebhookRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      url: HttpUrl,
+      eventTypes: EventTypes,
+      enabled: z.boolean().optional(),
+      description: z.string().trim().max(500).nullable().optional(),
+    })
+    .strict(),
+);
+export type CreateWorkspaceWebhookRequest = z.input<typeof CreateWorkspaceWebhookRequest>;
+
+/** The signing secret is returned exactly once, at creation. */
+export const CreateWorkspaceWebhookResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ webhook: WorkspaceWebhook, secret: z.string() }).strict(),
+);
+export type CreateWorkspaceWebhookResponse = z.infer<typeof CreateWorkspaceWebhookResponse>;
+
+export const UpdateWorkspaceWebhookRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      url: HttpUrl.optional(),
+      eventTypes: EventTypes.optional(),
+      enabled: z.boolean().optional(),
+      description: z.string().trim().max(500).nullable().optional(),
+    })
+    .strict(),
+);
+export type UpdateWorkspaceWebhookRequest = z.input<typeof UpdateWorkspaceWebhookRequest>;
+
+export const ListWorkspaceWebhooksResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ webhooks: z.array(WorkspaceWebhook) }).strict(),
+);
+export type ListWorkspaceWebhooksResponse = z.infer<typeof ListWorkspaceWebhooksResponse>;
+
+/** Organization webhooks fan out session events only; usage events are per-workspace. */
+export const OrganizationWebhookEventType = WorkspaceWebhookEventType.exclude([
+  "usage.threshold_reached",
+  "usage.exhausted",
+  "usage.period_reset",
+]);
+export type OrganizationWebhookEventType = z.infer<typeof OrganizationWebhookEventType>;
+const OrganizationEventTypes = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(WorkspaceWebhookEventType)
+    .min(1)
+    .max(WorkspaceWebhookEventType.options.length)
+    .refine((types) => types.every((type) => !type.startsWith("usage.")), {
+      message:
+        "Organization webhooks accept session events only; subscribe to usage events on a workspace webhook.",
+    })
+    .transform((types) => [...new Set(types)]),
+);
+
+export const OrganizationWebhook = /* @__PURE__ */ defineSchema(() =>
+  WorkspaceWebhook.omit({ workspaceId: true }).extend({
+    organizationId: z.string().uuid(),
+    eventTypes: z
+      .array(WorkspaceWebhookEventType)
+      .refine((types) => types.every((type) => !type.startsWith("usage.")), {
+        message:
+          "Organization webhooks accept session events only; subscribe to usage events on a workspace webhook.",
+      }),
+    workspaceFilter: IntegrationWorkspaceFilter.nullable(),
+  }),
+);
+export type OrganizationWebhook = z.infer<typeof OrganizationWebhook>;
+
+export const CreateOrganizationWebhookRequest = /* @__PURE__ */ defineSchema(() =>
+  CreateWorkspaceWebhookRequest.extend({
+    eventTypes: OrganizationEventTypes,
+    workspaceFilter: IntegrationWorkspaceFilter.nullable(),
+  }),
+);
+export type CreateOrganizationWebhookRequest = z.input<typeof CreateOrganizationWebhookRequest>;
+
+export const UpdateOrganizationWebhookRequest = /* @__PURE__ */ defineSchema(() =>
+  UpdateWorkspaceWebhookRequest.extend({
+    eventTypes: OrganizationEventTypes.optional(),
+    /** Explicit on every update: null covers all non-personal workspaces. */
+    workspaceFilter: IntegrationWorkspaceFilter.nullable(),
+  }),
+);
+export type UpdateOrganizationWebhookRequest = z.input<typeof UpdateOrganizationWebhookRequest>;
+
+export const CreateOrganizationWebhookResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ webhook: OrganizationWebhook, secret: z.string() }).strict(),
+);
+export type CreateOrganizationWebhookResponse = z.infer<typeof CreateOrganizationWebhookResponse>;
+
+export const ListOrganizationWebhooksResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ webhooks: z.array(OrganizationWebhook) }).strict(),
+);
+export type ListOrganizationWebhooksResponse = z.infer<typeof ListOrganizationWebhooksResponse>;
+
+export const WorkspaceWebhookDeliveryStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["pending", "delivered", "failed"]),
+);
+export type WorkspaceWebhookDeliveryStatus = z.infer<typeof WorkspaceWebhookDeliveryStatus>;
+
+export const WorkspaceWebhookDelivery = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.string().uuid(),
+      webhookId: z.string().uuid(),
+      eventId: z.string().uuid(),
+      eventType: z.string(),
+      status: WorkspaceWebhookDeliveryStatus,
+      attempts: z.number().int(),
+      lastStatus: z.number().int().nullable(),
+      lastError: z.string().nullable(),
+      nextAttemptAt: z.string().nullable(),
+      deliveredAt: z.string().nullable(),
+      failedAt: z.string().nullable(),
+      createdAt: z.string(),
+    })
+    .strict(),
+);
+export type WorkspaceWebhookDelivery = z.infer<typeof WorkspaceWebhookDelivery>;
+
+export const ListWorkspaceWebhookDeliveriesResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ deliveries: z.array(WorkspaceWebhookDelivery) }).strict(),
+);
+export type ListWorkspaceWebhookDeliveriesResponse = z.infer<
+  typeof ListWorkspaceWebhookDeliveriesResponse
+>;
+
+export const OrganizationWebhookDelivery = WorkspaceWebhookDelivery;
+export type OrganizationWebhookDelivery = z.infer<typeof OrganizationWebhookDelivery>;
+export const ListOrganizationWebhookDeliveriesResponse = ListWorkspaceWebhookDeliveriesResponse;
+export type ListOrganizationWebhookDeliveriesResponse = z.infer<
+  typeof ListOrganizationWebhookDeliveriesResponse
+>;
+
+/**
+ * The body POSTed to a webhook endpoint. Lifecycle events identify what
+ * changed; notification events also include their bounded display content.
+ */
+export const SessionWorkspaceWebhookEvent = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    lane: z.enum(["organization", "workspace"]).default("workspace"),
+    id: z.string().uuid(),
+    type: z.string(),
+    workspaceId: z.string().uuid(),
+    /** Present on new deliveries; optional for receivers of pre-upgrade deliveries. */
+    workspace: z
+      .object({
+        id: z.string().uuid(),
+        externalSource: z.string().nullable(),
+        externalId: z.string().nullable(),
+      })
+      .optional(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid().nullable(),
+    sequence: z.number().int(),
+    occurredAt: z.string(),
+    initiatingHuman: InitiatingHuman.nullable().optional(),
+    data: z
+      .object({
+        status: z.string().optional(),
+        reason: z.string().optional(),
+        /** Notification fields are optional for pre-upgrade thin deliveries. */
+        key: z.string().optional(),
+        title: z.string().optional(),
+        subtitle: z.string().optional(),
+        body: z.string().optional(),
+        facts: z.array(z.lazy(() => NotificationFact)).optional(),
+        link: z.lazy(() => NotificationLink).optional(),
+        urgency: z.lazy(() => NotificationUrgency).optional(),
+        replaced: z.boolean().optional(),
+        recipientSubjectId: z.string().optional(),
+        sender: z.object({ subjectId: z.string(), label: z.string() }).optional(),
+        /** Present when Opengeni notified no one, so the receiver may deliver it. */
+        undeliveredReason: z.lazy(() => NotificationUndeliveredReason).optional(),
+      })
+      .passthrough(),
+  }),
+);
+export type SessionWorkspaceWebhookEvent = z.infer<typeof SessionWorkspaceWebhookEvent>;
+/** Workspace allowance events have no synthetic session or turn identity.
+ * Optional null context fields let transport adapters share an envelope. */
+export const WorkspaceUsageWebhookEvent = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    lane: z.literal("workspace").default("workspace"),
+    id: z.string().uuid(),
+    type: z.enum(["usage.threshold_reached", "usage.exhausted", "usage.period_reset"]),
+    workspaceId: z.string().uuid(),
+    workspace: z
+      .object({
+        id: z.string().uuid(),
+        externalSource: z.string().nullable(),
+        externalId: z.string().nullable(),
+      })
+      .optional(),
+    sessionId: z.null().optional(),
+    turnId: z.null().optional(),
+    sequence: z.number().int().nonnegative().optional(),
+    occurredAt: z.string(),
+    data: z
+      .object({
+        scope: z.enum(["workspace", "member"]).optional(),
+        subjectId: z.string().nullable().optional(),
+        threshold: z.number().finite().optional(),
+        fraction: z.number().finite().nullable().optional(),
+        resetsAt: z.string().nullable().optional(),
+        status: UsageAllowanceStatus.optional(),
+        period: z.union([UsageAllowanceWindow, UsageAllowancePeriod, z.literal("*")]).optional(),
+      })
+      .passthrough(),
+  }),
+);
+export type WorkspaceUsageWebhookEvent = z.infer<typeof WorkspaceUsageWebhookEvent>;
+/**
+ * "Send test event": proves the endpoint is reachable and verifies the
+ * signature. It names the workspace but no session, turn or sequence.
+ */
+export const WorkspaceTestWebhookEvent = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    lane: z.enum(["organization", "workspace"]).default("workspace"),
+    id: z.string().uuid(),
+    type: z.literal(OPENGENI_WEBHOOK_TEST_EVENT_TYPE),
+    workspaceId: z.string().uuid(),
+    workspace: z
+      .object({
+        id: z.string().uuid(),
+        externalSource: z.string().nullable(),
+        externalId: z.string().nullable(),
+      })
+      .optional(),
+    sessionId: z.null().optional(),
+    turnId: z.null().optional(),
+    occurredAt: z.string(),
+    data: z.object({ webhookId: z.string().uuid().optional() }).passthrough(),
+  }),
+);
+export type WorkspaceTestWebhookEvent = z.infer<typeof WorkspaceTestWebhookEvent>;
+export const WorkspaceWebhookEvent = /* @__PURE__ */ defineSchema(() =>
+  z.union([SessionWorkspaceWebhookEvent, WorkspaceUsageWebhookEvent, WorkspaceTestWebhookEvent]),
+);
+export type WorkspaceWebhookEvent = z.infer<typeof WorkspaceWebhookEvent>;
+
+export const WorkspaceCredentialProvider = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      workspaceId: z.string().uuid(),
+      url: z.string(),
+      enabled: z.boolean(),
+      timeoutMs: z.number().int(),
+      createdAt: z.string(),
+      updatedAt: z.string(),
+    })
+    .strict(),
+);
+export type WorkspaceCredentialProvider = z.infer<typeof WorkspaceCredentialProvider>;
+
+export const PutWorkspaceCredentialProviderRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      url: HttpUrl,
+      enabled: z.boolean().optional(),
+      timeoutMs: z.number().int().min(1000).max(30000).optional(),
+    })
+    .strict(),
+);
+export type PutWorkspaceCredentialProviderRequest = z.input<
+  typeof PutWorkspaceCredentialProviderRequest
+>;
+
+/** `secret` is present only when the provider was first created. */
+export const PutWorkspaceCredentialProviderResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ provider: WorkspaceCredentialProvider, secret: z.string().optional() }).strict(),
+);
+export type PutWorkspaceCredentialProviderResponse = z.infer<
+  typeof PutWorkspaceCredentialProviderResponse
+>;
+
+export const GetWorkspaceCredentialProviderResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ provider: WorkspaceCredentialProvider.nullable() }).strict(),
+);
+export type GetWorkspaceCredentialProviderResponse = z.infer<
+  typeof GetWorkspaceCredentialProviderResponse
+>;
+
+export const OrganizationCredentialProvider = /* @__PURE__ */ defineSchema(() =>
+  WorkspaceCredentialProvider.omit({
+    workspaceId: true,
+  }).extend({
+    organizationId: z.string().uuid(),
+    workspaceFilter: IntegrationWorkspaceFilter.nullable(),
+  }),
+);
+export type OrganizationCredentialProvider = z.infer<typeof OrganizationCredentialProvider>;
+
+export const PutOrganizationCredentialProviderRequest =
+  /* @__PURE__ */ defineSchema(() =>
+    PutWorkspaceCredentialProviderRequest.extend({
+      /** Required; null explicitly covers all non-personal workspaces. PUT replaces configuration. */
+      workspaceFilter: IntegrationWorkspaceFilter.nullable(),
+    }),
+  );
+export type PutOrganizationCredentialProviderRequest = z.input<
+  typeof PutOrganizationCredentialProviderRequest
+>;
+
+export const PutOrganizationCredentialProviderResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ provider: OrganizationCredentialProvider, secret: z.string().optional() }).strict(),
+);
+export type PutOrganizationCredentialProviderResponse = z.infer<
+  typeof PutOrganizationCredentialProviderResponse
+>;
+
+export const GetOrganizationCredentialProviderResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ provider: OrganizationCredentialProvider.nullable() }).strict(),
+);
+export type GetOrganizationCredentialProviderResponse = z.infer<
+  typeof GetOrganizationCredentialProviderResponse
+>;
+
+/** Exact accepted-turn provenance, never an authorization grant. */
+export type CredentialProviderInitiatorContext = {
+  /** Agent delegation is identified by the newest frozen `via` hop. */
+  kind: "human" | "service" | "agent";
+  /** Full frozen causal identity, including an accepted service's display label. */
+  initiator: TurnInitiator;
+  /** Unmodified accepted context, including bounded `via` and coalesced `updateIds`. */
+  context: TurnInitiatorContext;
+};
+
+/** The body Opengeni POSTs to a workspace credential provider. */
+export type CredentialProviderRequest = {
+  type: "credentials.request";
+  lane: "organization" | "workspace";
+  /** Selected session-attached remote targets; providers must authorize each exact URL. */
+  mcpServers: { id: string; url: string }[];
+  /**
+   * `test` comes from an administrator's "Test connection": it is not a run,
+   * so `sessionId`, `rootSessionId`, `turnId` and `attemptId` are the nil
+   * UUID. Answer it as you would a run in this workspace (Opengeni shows only
+   * the names of what you return, never the values), or `not_applicable`.
+   */
+  purpose: "provision" | "renewal" | "test";
+  forceRefresh: boolean;
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  rootSessionId: string;
+  parentSessionId: string | null;
+  turnId: string;
+  attemptId: string;
+  initiator: { kind: string; subjectId?: string };
+  /** Informational, signed with the body. Optional only for pre-upgrade senders. */
+  initiatorContext?: CredentialProviderInitiatorContext;
+  initiatingHumanSubjectId: string | null;
+  /** Informational, not authority. Optional only for pre-upgrade senders. */
+  initiatingHuman?: InitiatingHuman | null;
+  sandboxBackend: string;
+  sandboxOs: string;
+};
+
+const ProviderAuthNeeded = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    reason: z.enum(["missing_connection", "expired", "insufficient_scope", "refresh_failed"]),
+    providerDomain: z.string().optional(),
+    connectionId: z.string().optional(),
+    scopes: z.array(z.string()).optional(),
+    resource: z.string().optional(),
+    authorizationUrl: z.string().optional(),
+    message: z.string().optional(),
+  }),
+);
+
+/**
+ * HTTPS Git credentials the host wants available to `git` in the sandbox.
+ * Opengeni stores them in a renewable file and points a credential helper at
+ * it, so a refreshed token applies to the next git command.
+ */
+const ProviderGitCredential = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    host: z
+      .string()
+      .trim()
+      .min(1)
+      .max(253)
+      .regex(/^[A-Za-z0-9.-]+(:\d{1,5})?$/, "host must be a bare hostname"),
+    username: z.string().min(1).max(256).optional(),
+    password: z.string().min(1).max(16384),
+  }),
+);
+
+const FORBIDDEN_MCP_HEADERS = new Set([
+  "host",
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "content-length",
+  "mcp-session-id",
+  "mcp-protocol-version",
+  "content-type",
+  "accept",
+]);
+
+/** Exact WHATWG normalization; IDs, URL credentials and fragments are never targets. */
+export function normalizeCredentialProviderMcpUrl(value: string): string {
+  const url = new URL(value);
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.hash) {
+    throw new Error("MCP credential URL must be an HTTP endpoint without credentials or fragment");
+  }
+  return url.href;
+}
+
+const ProviderMcpUrl = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(8)
+    .max(2048)
+    .refine((value) => {
+      try {
+        normalizeCredentialProviderMcpUrl(value);
+        return true;
+      } catch {
+        return false;
+      }
+    }, "MCP credential url must be an HTTP endpoint without credentials or fragment")
+    .transform(normalizeCredentialProviderMcpUrl),
+);
+
+/** Secret, turn-local headers for one session-attached remote MCP, by normalized URL only. */
+export const CredentialProviderMcpHeaders = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      url: ProviderMcpUrl,
+      headers: z.record(z.string(), z.string()),
+      expiresAt: z.iso.datetime({ offset: true }).optional(),
+    })
+    .strict()
+    .superRefine((entry, context) => {
+      const headers = Object.entries(entry.headers);
+      const seen = new Set<string>();
+      let bytes = 0;
+      if (headers.length === 0 || headers.length > 32) {
+        context.addIssue({ code: "custom", message: "MCP headers must contain 1–32 entries" });
+      }
+      for (const [name, value] of headers) {
+        const lower = name.toLowerCase();
+        if (
+          name.length > 128 ||
+          name.length === 0 ||
+          /[^!#$%&'*+.^_`|~0-9A-Za-z-]/.test(name) ||
+          FORBIDDEN_MCP_HEADERS.has(lower) ||
+          seen.has(lower)
+        ) {
+          context.addIssue({ code: "custom", message: "Invalid or duplicate MCP header name" });
+        }
+        seen.add(lower);
+        const valueBytes = new TextEncoder().encode(value).byteLength;
+        bytes += name.length + valueBytes;
+        if (valueBytes > 16384 || /[^\t\u0020-\u007e\u0080-\u00ff]/.test(value)) {
+          context.addIssue({ code: "custom", message: "Invalid or oversized MCP header value" });
+        }
+      }
+      if (bytes > 65536) {
+        context.addIssue({ code: "custom", message: "MCP header material exceeds 64 KiB" });
+      }
+    }),
+);
+export type CredentialProviderMcpHeaders = z.infer<typeof CredentialProviderMcpHeaders>;
+
+export const CredentialProviderMcpMaterial = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(CredentialProviderMcpHeaders)
+    .max(32)
+    .superRefine((entries, context) => {
+      if (new Set(entries.map((entry) => entry.url)).size !== entries.length) {
+        context.addIssue({ code: "custom", message: "Duplicate MCP server target" });
+      }
+    }),
+);
+export type CredentialProviderMcpMaterial = z.infer<typeof CredentialProviderMcpMaterial>;
+
+/** What a credential provider returns. Scope echoes are added by Opengeni. */
+export const CredentialProviderResponse = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("status", [
+    z.object({
+      status: z.literal("ok"),
+      environment: z.record(z.string(), z.string()).optional(),
+      files: z
+        .array(
+          z.object({
+            path: z.string(),
+            content: z.string(),
+            mode: z.enum(["0400", "0600"]).optional(),
+          }),
+        )
+        .optional(),
+      fileEnvironment: z.record(z.string(), z.string()).optional(),
+      git: z.array(ProviderGitCredential).max(16).optional(),
+      mcp: CredentialProviderMcpMaterial.optional(),
+      expiresAt: z.string().nullable().optional(),
+      authNeeded: z.array(ProviderAuthNeeded).optional(),
+    }),
+    z.object({ status: z.literal("not_applicable") }),
+    z.object({ status: z.literal("auth_needed"), authNeeded: z.array(ProviderAuthNeeded).min(1) }),
+  ]),
+);
+export type CredentialProviderResponse = z.infer<typeof CredentialProviderResponse>;
+
+/** Immediate signing-secret rotation; the new secret is returned once. */
+export const RotateWorkspaceCredentialProviderSecretResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ provider: WorkspaceCredentialProvider, secret: z.string() }).strict(),
+);
+export type RotateWorkspaceCredentialProviderSecretResponse = z.infer<
+  typeof RotateWorkspaceCredentialProviderSecretResponse
+>;
+export const RotateOrganizationCredentialProviderSecretResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ provider: OrganizationCredentialProvider, secret: z.string() }).strict(),
+);
+export type RotateOrganizationCredentialProviderSecretResponse = z.infer<
+  typeof RotateOrganizationCredentialProviderSecretResponse
+>;
+export const RotateWorkspaceWebhookSecretResponse = CreateWorkspaceWebhookResponse;
+export type RotateWorkspaceWebhookSecretResponse = z.infer<
+  typeof RotateWorkspaceWebhookSecretResponse
+>;
+export const RotateOrganizationWebhookSecretResponse = CreateOrganizationWebhookResponse;
+export type RotateOrganizationWebhookSecretResponse = z.infer<
+  typeof RotateOrganizationWebhookSecretResponse
+>;
+
+/**
+ * The outcome of one test request to a webhook or credential-provider
+ * endpoint. Nothing is stored: the request is sent once, synchronously.
+ * Credential values never appear; `credentials` names what a run would get.
+ */
+export const IntegrationEndpointTestResult = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      /** A 2xx answer (for a provider, also a valid response body). */
+      ok: z.boolean(),
+      /** The HTTP status, or null when the endpoint was not reached. */
+      status: z.number().int().nullable(),
+      durationMs: z.number().int().nonnegative(),
+      /** What went wrong, in one sentence, or null. */
+      error: z.string().nullable(),
+      /** The exact JSON body Opengeni signed and sent. */
+      request: z.string(),
+      /** The start of the endpoint's answer. Omitted for a successful provider answer. */
+      responseBody: z.string().nullable(),
+      credentials: z
+        .object({
+          status: z.enum(["ok", "not_applicable", "auth_needed"]),
+          environment: z.array(z.string()),
+          files: z.array(z.string()),
+          git: z.array(z.string()),
+          mcp: z.array(z.string()),
+          expiresAt: z.string().nullable(),
+          authNeeded: z.array(
+            z.object({
+              reason: z.string(),
+              providerDomain: z.string().nullable(),
+              message: z.string().nullable(),
+            }),
+          ),
+        })
+        .strict()
+        .nullable(),
+    })
+    .strict(),
+);
+export type IntegrationEndpointTestResult = z.infer<typeof IntegrationEndpointTestResult>;
+
+export const TestWorkspaceWebhookResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ result: IntegrationEndpointTestResult }).strict(),
+);
+export type TestWorkspaceWebhookResponse = z.infer<typeof TestWorkspaceWebhookResponse>;
+
+/** Tests the provider runs in this workspace would use: its own, else the organization's. */
+export const TestWorkspaceCredentialProviderResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      lane: z.enum(["workspace", "organization"]),
+      url: z.string(),
+      result: IntegrationEndpointTestResult,
+    })
+    .strict(),
+);
+export type TestWorkspaceCredentialProviderResponse = z.infer<
+  typeof TestWorkspaceCredentialProviderResponse
+>;
+
+/**
+ * Organization registrations that apply to one workspace, for workspace
+ * administrators: an enabled organization provider whose filter matches
+ * (even when this workspace overrides it) and the enabled organization
+ * webhooks that also receive this workspace's events. Never secrets.
+ */
+export const WorkspaceInheritedIntegrationsResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      credentialProvider: z
+        .object({ url: z.string(), timeoutMs: z.number().int(), updatedAt: z.string() })
+        .strict()
+        .nullable(),
+      webhooks: z.array(
+        z
+          .object({
+            id: z.string().uuid(),
+            url: z.string(),
+            eventTypes: z.array(WorkspaceWebhookEventType),
+            description: z.string().nullable(),
+          })
+          .strict(),
+      ),
+    })
+    .strict(),
+);
+export type WorkspaceInheritedIntegrationsResponse = z.infer<
+  typeof WorkspaceInheritedIntegrationsResponse
+>;