@opengeni/contracts 0.44.1 → 1.0.0

package/src/company-brain.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+
+import { WorkspaceStateKnowledge } from "./workspace-state";
+
+export const COMPANY_BRAIN_OKF_SCHEMA_VERSION = 1 as const;
+export const COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES = 512;
+export const COMPANY_BRAIN_GUIDANCE_CONTENT_MAX_CHARS = 262_144;
+export const COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES = 4 * 1024 * 1024;
+export const COMPANY_BRAIN_INSPECTOR_DEFAULT_LIMIT = 20;
+export const COMPANY_BRAIN_INSPECTOR_MAX_LIMIT = 50;
+export const COMPANY_BRAIN_INSPECTOR_CURSOR_MAX_CHARS = 1_024;
+export const COMPANY_BRAIN_PROPOSAL_CONTENT_MAX_BYTES = 16 * 1_024;
+export const COMPANY_BRAIN_PROPOSAL_RESPONSE_MAX_BYTES = 64 * 1_024;
+
+const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
+const boundedUtf8 = (maxBytes: number) =>
+  z.string().superRefine((value, context) => {
+    if (utf8Bytes(value) > maxBytes) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `must be at most ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
+
+export const CompanyBrainContextReceipt = z
+  .object({
+    id: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    rootSessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    acceptedAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+    sessionRole: z.enum(["root", "child"]),
+    memoryEnabled: z.boolean(),
+    // Snapshots are immutable: a turn accepted before the standing block was
+    // retired recorded `legacy_standing` and still reads back that way. This
+    // is a historical fact about that turn, not a mode anyone can select.
+    memoryPromptMode: z.enum(["legacy_standing", "retrieval_only"]),
+    companyProfileIncluded: z.boolean(),
+    instructionPolicyEntryHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    preferenceDescriptorHash: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/u)
+      .nullable(),
+    companyProfileSnapshotHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    turnContextSnapshotId: z.string().uuid(),
+    turnContextSnapshotHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    turnContextSnapshotSource: z.enum(["accepted_turn", "legacy_first_claim"]),
+    selectionHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    selectedMemoryCount: z.number().int().nonnegative().max(50),
+    renderedMemoryCount: z.number().int().nonnegative().max(50),
+    budgetOmittedMemoryCount: z.number().int().nonnegative().max(50),
+  })
+  .strict();
+export type CompanyBrainContextReceipt = z.infer<typeof CompanyBrainContextReceipt>;
+
+export const CompanyBrainContextReceiptPage = z
+  .object({
+    receipts: z.array(CompanyBrainContextReceipt).max(COMPANY_BRAIN_INSPECTOR_MAX_LIMIT),
+    nextCursor: z.string().min(1).max(COMPANY_BRAIN_INSPECTOR_CURSOR_MAX_CHARS).nullable(),
+    hasMore: z.boolean(),
+  })
+  .strict();
+export type CompanyBrainContextReceiptPage = z.infer<typeof CompanyBrainContextReceiptPage>;
+
+export const CompanyBrainKnowledgeProposal = z
+  .object({
+    id: z.string().uuid(),
+    authority: z.object({ kind: z.enum(["organization", "workspace", "personal"]) }).strict(),
+    targetKind: z.enum(["instruction_policy", "preference"]),
+    targetScope: z.string().min(1).max(96),
+    targetKey: z.string().min(1).max(96).nullable(),
+    content: boundedUtf8(COMPANY_BRAIN_PROPOSAL_CONTENT_MAX_BYTES),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    source: z.object({ claimId: z.string().uuid(), evidenceId: z.string().uuid() }).strict(),
+    status: z.literal("proposed"),
+    createdAt: z.string().datetime(),
+    projection: z
+      .object({
+        truncated: z.boolean(),
+        originalContentUtf8Bytes: z.number().int().nonnegative().max(1_048_576),
+      })
+      .strict(),
+  })
+  .strict();
+export type CompanyBrainKnowledgeProposal = z.infer<typeof CompanyBrainKnowledgeProposal>;
+
+export const CompanyBrainKnowledgeProposalPage = z
+  .object({
+    proposals: z.array(CompanyBrainKnowledgeProposal).max(COMPANY_BRAIN_INSPECTOR_MAX_LIMIT),
+    truncatedForCount: z.boolean(),
+    truncatedForResponseBytes: z.boolean(),
+    responseBytes: z.number().int().nonnegative().max(COMPANY_BRAIN_PROPOSAL_RESPONSE_MAX_BYTES),
+  })
+  .strict();
+export type CompanyBrainKnowledgeProposalPage = z.infer<typeof CompanyBrainKnowledgeProposalPage>;
+
+export const CompanyBrainGuidanceClassification = z.enum([
+  "company_profile",
+  "mandatory_rule",
+  "guide",
+]);
+export type CompanyBrainGuidanceClassification = z.infer<typeof CompanyBrainGuidanceClassification>;
+
+export const CompanyBrainGuidanceScope = z.enum(["organization", "workspace", "personal"]);
+export type CompanyBrainGuidanceScope = z.infer<typeof CompanyBrainGuidanceScope>;
+
+export const CompanyBrainGuidanceLifecycle = z.enum([
+  "active",
+  "proposal",
+  "inactive",
+  "rejected",
+  "superseded",
+  "expired",
+  "historical",
+]);
+export type CompanyBrainGuidanceLifecycle = z.infer<typeof CompanyBrainGuidanceLifecycle>;
+
+export const CompanyBrainGuidanceRelationship = z
+  .object({
+    type: z.enum(["corrects", "supersedes", "superseded_by"]),
+    targetId: z.string().min(1).max(512),
+  })
+  .strict();
+export type CompanyBrainGuidanceRelationship = z.infer<typeof CompanyBrainGuidanceRelationship>;
+
+export const CompanyBrainGuidanceEntry = z
+  .object({
+    id: z.string().min(1).max(512),
+    revisionId: z.string().uuid(),
+    path: z.string().min(1).max(512),
+    scope: CompanyBrainGuidanceScope,
+    classification: CompanyBrainGuidanceClassification,
+    title: z.string().min(1).max(160),
+    description: z.string().max(512).nullable(),
+    content: z.string().min(1).max(COMPANY_BRAIN_GUIDANCE_CONTENT_MAX_CHARS),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    revision: z.number().int().positive(),
+    active: z.boolean(),
+    lifecycle: CompanyBrainGuidanceLifecycle,
+    provenance: z
+      .object({
+        source: z.string().min(1).max(96),
+        sourceId: z.string().min(1).max(512).nullable(),
+        trust: z.string().min(1).max(96).nullable(),
+      })
+      .strict(),
+    relationships: z.array(CompanyBrainGuidanceRelationship).max(32),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type CompanyBrainGuidanceEntry = z.infer<typeof CompanyBrainGuidanceEntry>;
+
+export const CompanyBrainGuidanceTruncationReason = z.enum([
+  "company_profile_history",
+  "instruction_policy_history",
+  "preference_count",
+  "preference_history",
+  "aggregate_item_count",
+  "aggregate_content_bytes",
+]);
+export type CompanyBrainGuidanceTruncationReason = z.infer<
+  typeof CompanyBrainGuidanceTruncationReason
+>;
+
+export const CompanyBrainOkfPackage = z
+  .object({
+    kind: z.literal("opengeni.company_brain.okf"),
+    schemaVersion: z.literal(COMPANY_BRAIN_OKF_SCHEMA_VERSION),
+    workspaceId: z.string().uuid(),
+    generatedAt: z.string().datetime(),
+    permissions: z
+      .object({
+        guidance: z.literal("available"),
+        knowledge: z.enum(["available", "unavailable"]),
+      })
+      .strict(),
+    guidance: z
+      .object({
+        entries: z.array(CompanyBrainGuidanceEntry).max(COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES),
+        truncated: z.boolean(),
+        truncationReasons: z.array(CompanyBrainGuidanceTruncationReason).max(6),
+      })
+      .strict(),
+    knowledge: WorkspaceStateKnowledge,
+    omissions: z
+      .array(
+        z.enum([
+          "inaccessible_knowledge",
+          "document_bodies_use_documents_export",
+          "memory_bodies_and_provenance",
+          "secret_values_and_credentials",
+          "session_messages_and_task_notes",
+          "policy_and_preference_actor_identifiers",
+        ]),
+      )
+      .max(6),
+  })
+  .strict();
+export type CompanyBrainOkfPackage = z.infer<typeof CompanyBrainOkfPackage>;

package/src/company-profile.ts

@@ -1,4 +1,11 @@
 import { z } from "zod";
+import {
+  AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES,
+  AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
+} from "./agent-authored-durable-text";
+import { HumanInputQuestion } from "./index";
 
 export const COMPANY_PROFILE_SCALAR_MAX_CHARS = 2_048;
 export const COMPANY_PROFILE_ENTRY_MAX_CHARS = 1_024;
@@ -100,10 +107,56 @@ export const CompanyProfileContent = z
   });
 export type CompanyProfileContent = z.infer<typeof CompanyProfileContent>;
 
+/**
+ * The same profile, bounded for an **agent** author. The human `account:admin`
+ * route keeps `CompanyProfileContent` and its wider limits; this is the shape
+ * persisted by the first-party `company_profile_propose` tool. The current tool
+ * accepts only identity and mission and writes empty compatibility lists, but
+ * the validator must still read historical revisions without rewriting them.
+ */
+export const AgentAuthoredCompanyProfileContent = CompanyProfileContent.superRefine(
+  (value, context) => {
+    for (const field of ["identity", "mission"] as const) {
+      const scalar = value[field];
+      if (scalar !== null && scalar.length > AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS) {
+        context.addIssue({
+          code: "custom",
+          path: [field],
+          message: `${field} is ${scalar.length} characters. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+        });
+      }
+    }
+    for (const field of ["products", "customers", "goals", "constraints"] as const) {
+      for (const [index, entry] of value[field].entries()) {
+        if (entry.content.length > AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS) {
+          context.addIssue({
+            code: "custom",
+            path: [field, index, "content"],
+            message: `this entry is ${entry.content.length} characters. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+          });
+        }
+      }
+    }
+    const contentBytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    if (contentBytes > AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES) {
+      context.addIssue({
+        code: "custom",
+        message: `this profile is ${contentBytes} UTF-8 bytes. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+      });
+    }
+  },
+);
+export type AgentAuthoredCompanyProfileContent = z.infer<typeof AgentAuthoredCompanyProfileContent>;
+
 export const CompanyProfileRevisionIntent = z.enum(["active", "proposal"]);
 export type CompanyProfileRevisionIntent = z.infer<typeof CompanyProfileRevisionIntent>;
 
-export const CompanyProfileProvenanceSource = z.enum(["human", "durable_learning", "migration"]);
+export const CompanyProfileProvenanceSource = z.enum([
+  "human",
+  "agent_admin",
+  "durable_learning",
+  "migration",
+]);
 export type CompanyProfileProvenanceSource = z.infer<typeof CompanyProfileProvenanceSource>;
 
 export const CompanyProfilePrincipalKind = z.enum(["human_session", "agent_attempt", "service"]);
@@ -240,6 +293,119 @@ export const CompanyProfileMutationResponse = z.object({
 });
 export type CompanyProfileMutationResponse = z.infer<typeof CompanyProfileMutationResponse>;
 
+export const COMPANY_PROFILE_AGENT_APPROVE_OPTION = "activate" as const;
+export const COMPANY_PROFILE_AGENT_REJECT_OPTION = "skip" as const;
+
+export const CompanyProfileAgentPolicyMode = z.enum(["off", "suggest", "automatic"]);
+export type CompanyProfileAgentPolicyMode = z.infer<typeof CompanyProfileAgentPolicyMode>;
+
+export const CompanyProfileAgentPolicy = z.object({
+  organizationId: z.string().uuid(),
+  mode: CompanyProfileAgentPolicyMode,
+  version: z.number().int().nonnegative(),
+  updatedAt: z.string().datetime({ offset: true }),
+  changed: z.boolean().optional(),
+});
+export type CompanyProfileAgentPolicy = z.infer<typeof CompanyProfileAgentPolicy>;
+
+export const UpdateCompanyProfileAgentPolicyRequest = z
+  .object({
+    mode: CompanyProfileAgentPolicyMode,
+    expectedVersion: z.number().int().nonnegative(),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateCompanyProfileAgentPolicyRequest = z.infer<
+  typeof UpdateCompanyProfileAgentPolicyRequest
+>;
+
+export const CompanyProfileAgentAttempt = z
+  .object({
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    agentSubjectId: z.string().trim().min(1).max(1_024),
+  })
+  .strict();
+export type CompanyProfileAgentAttempt = z.infer<typeof CompanyProfileAgentAttempt>;
+
+export const CompanyProfileAgentProposalRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    profile: CompanyProfileContent,
+    reason: z.string().trim().min(1).max(COMPANY_PROFILE_REASON_MAX_CHARS),
+  })
+  .strict();
+export type CompanyProfileAgentProposalRequest = z.infer<typeof CompanyProfileAgentProposalRequest>;
+
+// z.lazy avoids an import cycle because HumanInputQuestion is declared in the
+// root contracts module that re-exports this file.
+export const CompanyProfileAgentHumanInputPrompt = z.object({
+  questions: z.array(z.lazy(() => HumanInputQuestion)).length(1),
+  allowSkip: z.literal(false),
+});
+export type CompanyProfileAgentHumanInputPrompt = z.infer<
+  typeof CompanyProfileAgentHumanInputPrompt
+>;
+
+export const CompanyProfileAgentReviewRequiredReceipt = z.object({
+  status: z.literal("confirmation_required"),
+  operationId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  revision: CompanyProfileRevision,
+  policyMode: z.literal("suggest"),
+  humanInput: CompanyProfileAgentHumanInputPrompt,
+  confirmWith: z.literal("company_profile_confirm"),
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentReviewRequiredReceipt = z.infer<
+  typeof CompanyProfileAgentReviewRequiredReceipt
+>;
+
+export const CompanyProfileAgentAutomaticActivationReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  automaticActivationReceiptId: z.string().uuid(),
+  policyMode: z.literal("automatic"),
+  mutation: CompanyProfileMutationResponse,
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentAutomaticActivationReceipt = z.infer<
+  typeof CompanyProfileAgentAutomaticActivationReceipt
+>;
+
+export const CompanyProfileAgentProposalReceipt = z.discriminatedUnion("status", [
+  CompanyProfileAgentReviewRequiredReceipt,
+  CompanyProfileAgentAutomaticActivationReceipt,
+]);
+export type CompanyProfileAgentProposalReceipt = z.infer<typeof CompanyProfileAgentProposalReceipt>;
+
+export const CompanyProfileAgentConfirmRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    proposalReceiptId: z.string().uuid(),
+    humanInputRequestId: z.string().uuid(),
+  })
+  .strict();
+export type CompanyProfileAgentConfirmRequest = z.infer<typeof CompanyProfileAgentConfirmRequest>;
+
+export const CompanyProfileAgentConfirmationReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  confirmationReceiptId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  humanInputRequestId: z.string().uuid(),
+  mutation: CompanyProfileMutationResponse,
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentConfirmationReceipt = z.infer<
+  typeof CompanyProfileAgentConfirmationReceipt
+>;
+
 export const CompanyProfileDiffRequest = z
   .object({ fromRevisionId: z.string().uuid(), toRevisionId: z.string().uuid() })
   .refine((value) => value.fromRevisionId !== value.toRevisionId, {

package/src/connect.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import { IntegrationInstanceKey, IntegrationSource } from "./index";
+
+const opaqueId = z.string().min(1).max(512);
+export const ConnectOwnership = z.enum(["personal", "workspace"]);
+export type ConnectOwnership = z.infer<typeof ConnectOwnership>;
+export const ConnectProvider = z
+  .object({
+    id: opaqueId,
+    label: z.string().min(1).max(256),
+    family: opaqueId,
+    readiness: z.enum(["available", "needs_configuration", "operator_only", "unsupported"]),
+    reason: z.string().max(1024).optional(),
+    ownership: z.array(ConnectOwnership).max(2),
+    setup: z
+      .array(
+        z.enum(["none", "oauth", "credentials", "device", "installation", "openapi", "graphql"]),
+      )
+      .max(7),
+  })
+  .strict();
+export type ConnectProvider = z.infer<typeof ConnectProvider>;
+export const ConnectAccount = z
+  .object({
+    id: opaqueId,
+    providerId: opaqueId,
+    version: z.number().int().positive().optional(),
+    label: z.string().max(256),
+    ownership: ConnectOwnership,
+    status: z.enum(["connected", "auth_needed", "disabled"]),
+  })
+  .strict();
+export type ConnectAccount = z.infer<typeof ConnectAccount>;
+export const ConnectResource = z
+  .object({ id: opaqueId, label: z.string().max(512), kind: opaqueId })
+  .strict();
+export type ConnectResource = z.infer<typeof ConnectResource>;
+export const ConnectNextAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("authorize"), url: z.string().url().max(16_384) }).strict(),
+  z
+    .object({
+      type: z.literal("credentials"),
+      fields: z
+        .array(
+          z
+            .object({
+              name: opaqueId,
+              label: z.string().max(256),
+              required: z.boolean(),
+              secret: z.boolean(),
+              options: z
+                .array(z.object({ value: opaqueId, label: z.string().max(512) }).strict())
+                .max(1000)
+                .optional(),
+            })
+            .strict(),
+        )
+        .max(32),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("wait"),
+      pollAfterMs: z.number().int().min(250).max(60_000),
+      userCode: z.string().max(128).optional(),
+      verificationUrl: z.string().url().max(2048).optional(),
+    })
+    .strict(),
+  z
+    .object({ type: z.literal("select_account"), accounts: z.array(ConnectAccount).max(100) })
+    .strict(),
+  z
+    .object({
+      type: z.literal("select_resources"),
+      resources: z.array(ConnectResource).max(100),
+      cursor: z.string().max(2048).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("preview"),
+      previewId: opaqueId,
+      contentHash: opaqueId,
+      operations: z.array(ConnectResource).max(2000),
+    })
+    .strict(),
+  z.object({ type: z.literal("none") }).strict(),
+]);
+export type ConnectNextAction = z.infer<typeof ConnectNextAction>;
+export const ConnectInstallationTarget = z
+  .object({
+    instanceKey: IntegrationInstanceKey,
+    displayName: z.string().min(1).max(200),
+    expectedInstanceVersion: z.number().int().positive().optional(),
+  })
+  .strict();
+export type ConnectInstallationTarget = z.infer<typeof ConnectInstallationTarget>;
+export const ConnectAttemptState = z.enum([
+  "ready",
+  "requires_user_action",
+  "credential_input",
+  "provider_wait",
+  "account_selection",
+  "resource_selection",
+  "preview",
+  "installing",
+  "connected_but_incomplete",
+  "complete",
+  "cancelled",
+  "expired",
+  "failed",
+  "uncertain",
+]);
+export const ConnectAttempt = z
+  .object({
+    id: opaqueId,
+    workspaceId: opaqueId,
+    providerId: opaqueId,
+    ownership: ConnectOwnership,
+    revision: z.number().int().positive(),
+    state: ConnectAttemptState,
+    credentialsCommitted: z.boolean(),
+    integrationInstalled: z.boolean(),
+    completionRequirement: z.enum(["connection", "integration", "provider_setup"]),
+    nextAction: ConnectNextAction,
+    expiresAt: z.string().datetime({ offset: true }),
+    account: ConnectAccount.optional(),
+    installationTarget: ConnectInstallationTarget.optional(),
+    source: IntegrationSource.optional(),
+    error: z
+      .object({ code: opaqueId, message: z.string().max(2048), retryable: z.boolean() })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (
+      value.state === "complete" &&
+      value.completionRequirement === "integration" &&
+      !value.integrationInstalled
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Complete setup requires an installed integration",
+      });
+    }
+    if (
+      value.state === "complete" &&
+      value.completionRequirement === "connection" &&
+      !value.credentialsCommitted
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Connection setup requires committed credentials",
+      });
+    }
+    if (
+      ["complete", "cancelled", "expired"].includes(value.state) &&
+      value.nextAction.type !== "none"
+    ) {
+      context.addIssue({ code: "custom", message: "A terminal setup has no next action" });
+    }
+  });
+export type ConnectAttempt = z.infer<typeof ConnectAttempt>;
+export const ConnectAdvance = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("credentials"),
+      values: z.record(z.string().max(256), z.string().max(16_384)),
+    })
+    .strict(),
+  z.object({ type: z.literal("account"), accountId: opaqueId }).strict(),
+  z.object({ type: z.literal("resources"), resourceIds: z.array(opaqueId).max(1000) }).strict(),
+  z
+    .object({
+      type: z.literal("install"),
+      previewId: opaqueId,
+      contentHash: opaqueId,
+      operationIds: z.array(opaqueId).max(2000),
+    })
+    .strict(),
+  z.object({ type: z.literal("retry") }).strict(),
+]);
+export type ConnectAdvance = z.infer<typeof ConnectAdvance>;
+export const ConnectOperationRequest = z
+  .object({
+    expectedRevision: z.number().int().positive().safe(),
+    idempotencyKey: opaqueId,
+  })
+  .strict();
+export const AdvanceConnectRequest = ConnectOperationRequest.extend({ action: ConnectAdvance });
+export const BeginConnectRequest = z
+  .object({
+    providerId: opaqueId,
+    ownership: ConnectOwnership,
+    // URL parsing validates separately; never transform this original string.
+    returnUrl: z.string().min(1).max(4096),
+    idempotencyKey: opaqueId,
+    reconnectAccountId: opaqueId.optional(),
+    installationTarget: ConnectInstallationTarget.optional(),
+  })
+  .strict();

package/src/connection-account-label.ts

@@ -0,0 +1,46 @@
+/** Display identity from an already authorized connection. Never used to select credentials. */
+export function connectionAccountIdentityLabel(
+  metadata: Record<string, unknown>,
+  fallback: string,
+): string {
+  const text = (value: unknown): string | undefined =>
+    typeof value === "string" && value.trim()
+      ? value
+          .replace(/[\u0000-\u001f\u007f]/gu, " ")
+          .trim()
+          .slice(0, 180)
+      : undefined;
+  const nestedName = (value: unknown): unknown =>
+    value && typeof value === "object" ? (value as Record<string, unknown>).name : value;
+  const name =
+    [
+      metadata.email,
+      metadata.providerEmail,
+      metadata.googleEmail,
+      metadata.gmailEmail,
+      metadata.accountLabel,
+      metadata.displayName,
+      metadata.providerDisplayName,
+      metadata.googleDisplayName,
+      metadata.accountName,
+      metadata.name,
+      metadata.slackUserName,
+      metadata.username,
+      metadata.slackUserId,
+    ]
+      .map(text)
+      .find(Boolean) ?? fallback;
+  const workspace = [
+    metadata.slackTeamName,
+    metadata.teamName,
+    metadata.workspaceName,
+    metadata.team_name,
+    metadata.workspace_name,
+    nestedName(metadata.team),
+    nestedName(metadata.workspace),
+    metadata.slackTeamId,
+  ]
+    .map(text)
+    .find(Boolean);
+  return [...new Set([name, workspace].filter(Boolean))].join(" · ");
+}