@opengeni/contracts 0.27.0 → 0.30.0

package/dist/scoped-knowledge.d.ts

@@ -0,0 +1,233 @@
+import { z } from "zod";
+/** Tenant scope for normalized knowledge and source provenance. */
+export declare const ScopedKnowledgeScopeKind: z.ZodEnum<{
+    organization: "organization";
+    personal: "personal";
+    workspace: "workspace";
+}>;
+export type ScopedKnowledgeScopeKind = z.infer<typeof ScopedKnowledgeScopeKind>;
+export type ScopedKnowledgeScope = {
+    kind: "organization";
+    workspaceId: null;
+    subjectId: null;
+} | {
+    kind: "workspace";
+    workspaceId: string;
+    subjectId: null;
+} | {
+    kind: "personal";
+    workspaceId: string | null;
+    subjectId: string;
+};
+export declare const ScopedKnowledgeActorKind: z.ZodEnum<{
+    human: "human";
+    service: "service";
+}>;
+export type ScopedKnowledgeActorKind = z.infer<typeof ScopedKnowledgeActorKind>;
+/**
+ * Immutable write provenance. A service actor may retain a causal human, but
+ * the service identity never substitutes for that human on personal reads.
+ */
+export type ScopedKnowledgeActor = {
+    kind: ScopedKnowledgeActorKind;
+    subjectId: string;
+    initiatingHumanSubjectId: string | null;
+};
+export declare const KnowledgeLifecycleState: z.ZodEnum<{
+    active: "active";
+    deleted: "deleted";
+    revoked: "revoked";
+}>;
+export type KnowledgeLifecycleState = z.infer<typeof KnowledgeLifecycleState>;
+export declare const KnowledgeLifecycleEventType: z.ZodEnum<{
+    acl_changed: "acl_changed";
+    deleted: "deleted";
+    object_version_added: "object_version_added";
+    restored: "restored";
+    revoked: "revoked";
+    sync_failed: "sync_failed";
+    sync_succeeded: "sync_succeeded";
+}>;
+export type KnowledgeLifecycleEventType = z.infer<typeof KnowledgeLifecycleEventType>;
+export declare const KnowledgeSyncRunState: z.ZodEnum<{
+    failed: "failed";
+    started: "started";
+    succeeded: "succeeded";
+}>;
+export type KnowledgeSyncRunState = z.infer<typeof KnowledgeSyncRunState>;
+export declare const KnowledgeClaimOrigin: z.ZodEnum<{
+    explicit: "explicit";
+    inferred: "inferred";
+}>;
+export type KnowledgeClaimOrigin = z.infer<typeof KnowledgeClaimOrigin>;
+export declare const KnowledgeClaimRelationType: z.ZodEnum<{
+    conflicts_with: "conflicts_with";
+    supersedes: "supersedes";
+}>;
+export type KnowledgeClaimRelationType = z.infer<typeof KnowledgeClaimRelationType>;
+export declare const KnowledgeClaimEvidencePolarity: z.ZodEnum<{
+    contradicts: "contradicts";
+    supports: "supports";
+}>;
+export type KnowledgeClaimEvidencePolarity = z.infer<typeof KnowledgeClaimEvidencePolarity>;
+export declare const KnowledgeClaimReviewState: z.ZodEnum<{
+    approved: "approved";
+    proposed: "proposed";
+    rejected: "rejected";
+    revoked: "revoked";
+}>;
+export type KnowledgeClaimReviewState = z.infer<typeof KnowledgeClaimReviewState>;
+export declare const KnowledgeFactObjectKind: z.ZodEnum<{
+    boolean: "boolean";
+    entity: "entity";
+    json: "json";
+    number: "number";
+    text: "text";
+    timestamp: "timestamp";
+}>;
+export type KnowledgeFactObjectKind = z.infer<typeof KnowledgeFactObjectKind>;
+export declare const KnowledgeChangeProposalTargetKind: z.ZodEnum<{
+    instruction_policy: "instruction_policy";
+    preference: "preference";
+}>;
+export type KnowledgeChangeProposalTargetKind = z.infer<typeof KnowledgeChangeProposalTargetKind>;
+export type KnowledgeProviderRecord = {
+    id: string;
+    accountId: string;
+    scope: ScopedKnowledgeScope;
+    providerKey: string;
+    externalTenantId: string;
+    lifecycleState: KnowledgeLifecycleState;
+    lifecycleGeneration: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type KnowledgeSourceRecord = {
+    id: string;
+    accountId: string;
+    providerId: string;
+    scope: ScopedKnowledgeScope;
+    externalSourceId: string;
+    sourceKind: string;
+    sourceUri: string | null;
+    currentAclGeneration: number | null;
+    syncGeneration: number;
+    syncCursor: string | null;
+    lifecycleState: KnowledgeLifecycleState;
+    lifecycleGeneration: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type KnowledgeSourceAclVersionRecord = {
+    id: string;
+    accountId: string;
+    sourceId: string;
+    generation: number;
+    aclVersion: string | null;
+    aclHash: string;
+    audience: ScopedKnowledgeScope;
+    agentAccess: boolean;
+    createdAt: string;
+};
+export type KnowledgeSyncRunRecord = {
+    id: string;
+    accountId: string;
+    sourceId: string;
+    operationId: string;
+    state: KnowledgeSyncRunState;
+    inputSyncGeneration: number;
+    inputLifecycleGeneration: number;
+    inputCursor: string | null;
+    outputCursor: string | null;
+    watermark: string | null;
+    metadata: Record<string, unknown>;
+    errorCode: string | null;
+    startedAt: string;
+    completedAt: string | null;
+};
+export type KnowledgeSourceObjectRecord = {
+    id: string;
+    accountId: string;
+    sourceId: string;
+    scope: ScopedKnowledgeScope;
+    externalObjectId: string;
+    documentId: string | null;
+    lifecycleState: KnowledgeLifecycleState;
+    lifecycleGeneration: number;
+    versionGeneration: number;
+    currentVersionId: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type KnowledgeDocumentVersionRecord = {
+    id: string;
+    accountId: string;
+    sourceId: string;
+    objectId: string;
+    scope: ScopedKnowledgeScope;
+    versionGeneration: number;
+    externalVersionId: string;
+    contentSha256: string;
+    ingestionKey: string;
+    aclVersionId: string;
+    aclGeneration: number;
+    documentId: string | null;
+    fileId: string | null;
+    createdAt: string;
+};
+export type KnowledgeEntityRecord = {
+    id: string;
+    accountId: string;
+    scope: ScopedKnowledgeScope;
+    entityType: string;
+    normalizedKey: string;
+    displayName: string;
+    createdAt: string;
+};
+export type KnowledgeFactRecord = {
+    id: string;
+    accountId: string;
+    scope: ScopedKnowledgeScope;
+    subjectEntityId: string;
+    predicateKey: string;
+    objectKind: KnowledgeFactObjectKind;
+    objectEntityId: string | null;
+    objectValue: unknown | null;
+    objectHash: string;
+    createdAt: string;
+};
+export type KnowledgeClaimRecord = {
+    id: string;
+    accountId: string;
+    scope: ScopedKnowledgeScope;
+    factId: string;
+    origin: KnowledgeClaimOrigin;
+    confidenceBps: number;
+    effectiveAt: string;
+    expiresAt: string | null;
+    extractionMethod: string;
+    modelProvider: string | null;
+    modelName: string | null;
+    modelVersion: string | null;
+    createdAt: string;
+};
+export type EligibleKnowledgeClaim = {
+    claim: KnowledgeClaimRecord;
+    fact: KnowledgeFactRecord;
+    reviewState: "approved";
+    supportingEvidenceCount: number;
+};
+export type KnowledgeChangeProposalRecord = {
+    id: string;
+    accountId: string;
+    scope: ScopedKnowledgeScope;
+    targetKind: KnowledgeChangeProposalTargetKind;
+    targetScope: string;
+    targetKey: string | null;
+    content: string;
+    contentHash: string;
+    claimId: string;
+    evidenceId: string;
+    status: "proposed";
+    createdAt: string;
+};

package/package.json

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

package/src/index.ts

@@ -676,6 +676,10 @@ export const DEFAULT_FIRST_PARTY_MCP_PERMISSIONS = [
   "sessions:read",
   "sessions:create",
   "sessions:control",
+  // Read-only connection discovery lets the selected first-party connector
+  // tools resolve an already-installed workspace principal. Credentials stay
+  // inside the broker and remain subject to each tool's own authorization.
+  "connections:read",
   "variable-sets:use",
   "variable-sets:manage",
   "rigs:use",
@@ -732,6 +736,11 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "social_connections_list",
   "social_posts_recent",
   "social_daily_analysis_context",
+  "social_search_live",
+  "social_mentions_live",
+  "social_thread_fetch",
+  "social_posts_sync",
+  "social_post_reply",
   "scheduled_tasks_list",
   "scheduled_tasks_get",
   "scheduled_tasks_create",
@@ -760,12 +769,13 @@ export const FirstPartyMcpToolName = z.enum(FIRST_PARTY_MCP_TOOL_NAMES);
 export type FirstPartyMcpToolName = z.infer<typeof FirstPartyMcpToolName>;
 
 /**
- * Every catalogued OpenGeni tool is selected by default. Registration-time
- * authorization remains the independent access boundary; an explicit session
- * policy may narrow this model-visible set.
+ * Connector-wide tools are explicit-only. Ordinary session omission selects
+ * the non-connector catalog, while an explicit session policy may still select
+ * any catalogued connector tool and remains independently permission-gated.
  */
-export const DEFAULT_FIRST_PARTY_MCP_TOOLS =
-  FIRST_PARTY_MCP_TOOL_NAMES satisfies readonly FirstPartyMcpToolName[];
+export const DEFAULT_FIRST_PARTY_MCP_TOOLS = FIRST_PARTY_MCP_TOOL_NAMES.filter(
+  (name) => !name.startsWith("social_") && !name.startsWith("slack_bot_"),
+) satisfies readonly FirstPartyMcpToolName[];
 
 export function prefixedMcpToolName(registryId: string, toolName: string): string {
   return `${registryId}__${toolName}`;
@@ -2538,6 +2548,46 @@ export const McpServerConnectionRef = z
   });
 export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRef>;
 
+/** Internal frozen authority for one personal MCP connection. */
+export const McpPersonalConnectionDelegation = z
+  .object({
+    serverId: z.string().min(1).max(256),
+    connectionId: z.string().uuid(),
+    ownerSubjectId: z.string().min(1).max(512),
+    providerDomain: z.string().min(1).max(2048),
+    kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
+  })
+  .strict();
+export type McpPersonalConnectionDelegation = z.infer<typeof McpPersonalConnectionDelegation>;
+
+/**
+ * Exact personal MCP authority frozen on one causal turn or scheduled task.
+ * One server can have at most one grant; bounded validation keeps corrupt JSON
+ * from becoming executable credential authority at a DB read boundary.
+ */
+export const McpPersonalConnectionDelegations = z
+  .array(McpPersonalConnectionDelegation)
+  .max(128)
+  .superRefine((delegations, context) => {
+    const seen = new Set<string>();
+    for (const [index, delegation] of delegations.entries()) {
+      if (seen.has(delegation.serverId)) {
+        context.addIssue({
+          code: "custom",
+          message: "personal MCP delegations must be unique by serverId",
+          path: [index, "serverId"],
+        });
+      }
+      seen.add(delegation.serverId);
+    }
+  });
+
+export const McpPersonalConnectionSummary = McpPersonalConnectionDelegation.pick({
+  serverId: true,
+  providerDomain: true,
+});
+export type McpPersonalConnectionSummary = z.infer<typeof McpPersonalConnectionSummary>;
+
 export type McpCredentialsRequest = {
   accountId: string;
   workspaceId: string;
@@ -2565,6 +2615,7 @@ export type McpCredentialsRequest = {
 
 export type McpCredentialAuthNeededReason =
   | CredentialAuthNeededReason
+  | "personal_authority_unavailable"
   | "unsupported_auth"
   | "resource_scope_unavailable";
 
@@ -4011,6 +4062,8 @@ export const SessionTurn = z.object({
   lineage: z.record(z.string(), z.unknown()),
   initiator: TurnInitiator,
   initiatorContext: TurnInitiatorContext,
+  /** Secret-safe projection of the exact personal authority frozen on this turn. */
+  personalConnections: z.array(McpPersonalConnectionSummary).default([]),
   cancelledBy: z.string().nullable(),
   cancelReason: z.string().nullable(),
   startedAt: z.string().nullable(),
@@ -4498,6 +4551,8 @@ export type SessionPendingInputPreview = z.infer<typeof SessionPendingInputPrevi
 export const SessionQueueSnapshot = z.object({
   version: z.number().int().nonnegative(),
   effectiveControl: EffectiveSessionControl,
+  /** Secret-safe personal MCP summaries frozen on the exact active turn. */
+  activePersonalConnections: z.array(McpPersonalConnectionSummary).default([]),
   /**
    * True while the latest attempt is interrupted but has not durably proved
    * quiescence: no more inference, user-visible output, or workspace-persistence
@@ -4865,6 +4920,9 @@ export const ScheduledTask = z.object({
   runMode: ScheduledTaskRunMode,
   overlapPolicy: ScheduledTaskOverlapPolicy,
   agentConfig: ScheduledTaskAgentConfig,
+  createdBy: TurnInitiator.default({ kind: "service", subjectId: "unattributed-legacy" }),
+  createdByContext: TurnInitiatorContext.default({}),
+  personalConnections: z.array(McpPersonalConnectionSummary).default([]),
   reusableSessionId: z.string().uuid().nullable(),
   variableSetId: z.string().uuid().nullable().default(null),
   /** @deprecated use variableSetId */
@@ -5185,6 +5243,7 @@ export type EnablePackRequest = z.infer<typeof EnablePackRequest>;
 
 export const SocialProvider = z.enum([
   "x",
+  "reddit",
   "linkedin",
   "instagram",
   "facebook",
@@ -5257,6 +5316,19 @@ export const CreateSocialPostRequest = z.object({
 });
 export type CreateSocialPostRequest = z.infer<typeof CreateSocialPostRequest>;
 
+// Social OAuth is first-party (X / Reddit REST APIs), distinct from the MCP
+// integrations OAuth flow: these providers have no MCP resource metadata, so
+// endpoints are pinned per provider and tokens live in social_connections.
+export const SocialOAuthProviderId = z.enum(["x", "reddit"]);
+export type SocialOAuthProviderId = z.infer<typeof SocialOAuthProviderId>;
+
+export const SocialOAuthStartRequest = z.object({
+  provider: SocialOAuthProviderId,
+  scopes: z.array(z.string().min(1)).optional(),
+  returnPath: z.string().optional(),
+});
+export type SocialOAuthStartRequest = z.infer<typeof SocialOAuthStartRequest>;
+
 export const ConnectionKind = z.enum(["oauth2", "api_key", "app_install", "delegated"]);
 export type ConnectionKind = z.infer<typeof ConnectionKind>;
 
@@ -5306,12 +5378,81 @@ export const ConnectionMetadata = z.object({
 });
 export type ConnectionMetadata = z.infer<typeof ConnectionMetadata>;
 
+type PersonalSlackCanonicalConnection = Pick<
+  ConnectionMetadata,
+  "id" | "status" | "createdAt" | "updatedAt"
+>;
+
+const PERSONAL_SLACK_CONNECTION_STATUS_RANK = {
+  active: 0,
+  needs_reauth: 1,
+  error: 2,
+  revoked: 3,
+} as const satisfies Record<ConnectionStatus, number>;
+
+/**
+ * Canonical ordering for duplicate subject-owned Personal Slack rows.
+ *
+ * PostgreSQL broker lookup mirrors this exact sequence: usable status first,
+ * then newest update, newest creation, and immutable UUID descending.
+ */
+export function comparePersonalSlackCanonicalConnections(
+  left: PersonalSlackCanonicalConnection,
+  right: PersonalSlackCanonicalConnection,
+): number {
+  const statusDelta =
+    PERSONAL_SLACK_CONNECTION_STATUS_RANK[left.status] -
+    PERSONAL_SLACK_CONNECTION_STATUS_RANK[right.status];
+  if (statusDelta !== 0) return statusDelta;
+
+  const updatedAtDelta = compareDescending(
+    canonicalConnectionTimestamp(left.updatedAt),
+    canonicalConnectionTimestamp(right.updatedAt),
+  );
+  if (updatedAtDelta !== 0) return updatedAtDelta;
+
+  const createdAtDelta = compareDescending(
+    canonicalConnectionTimestamp(left.createdAt),
+    canonicalConnectionTimestamp(right.createdAt),
+  );
+  if (createdAtDelta !== 0) return createdAtDelta;
+
+  return compareDescending(left.id, right.id);
+}
+
+export function selectCanonicalPersonalSlackConnection<T extends PersonalSlackCanonicalConnection>(
+  connections: readonly T[],
+): T | null {
+  let selected: T | null = null;
+  for (const connection of connections) {
+    if (!selected || comparePersonalSlackCanonicalConnections(connection, selected) < 0) {
+      selected = connection;
+    }
+  }
+  return selected;
+}
+
+function canonicalConnectionTimestamp(value: string): number {
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : Number.NEGATIVE_INFINITY;
+}
+
+function compareDescending(left: number | string, right: number | string): number {
+  if (left === right) return 0;
+  return left > right ? -1 : 1;
+}
+
 export const ConnectionCredentialBundle = z.record(z.string(), z.unknown());
 export type ConnectionCredentialBundle = z.infer<typeof ConnectionCredentialBundle>;
 
+export const ConnectionOwnership = z.enum(["workspace", "personal"]);
+export type ConnectionOwnership = z.infer<typeof ConnectionOwnership>;
+
 export const CreateConnectionRequest = z.object({
   providerDomain: z.string().min(1),
   kind: ConnectionKind,
+  ownership: ConnectionOwnership.optional(),
+  /** @deprecated use ownership */
   subjectId: z.string().min(1).nullable().optional(),
   credential: ConnectionCredentialBundle,
   grantedScopes: z.array(z.string().min(1)).default([]),
@@ -5361,6 +5502,7 @@ export const OAuthStartRequest = z
     requestedScopes: z.array(z.string().min(1)).default([]),
     returnPath: z.string().min(1).optional(),
     connectionId: z.string().uuid().optional(),
+    ownership: ConnectionOwnership.optional(),
     oauthClient: z
       .object({
         clientId: z.string().min(1),
@@ -5646,8 +5788,8 @@ export const Session = z.object({
   // Non-default first-party MCP token permissions (manager-style sessions);
   // null means the fixed worker default set.
   firstPartyMcpPermissions: z.array(Permission).nullable(),
-  // Exact model-visible OpenGeni selection. All catalogued tools are selected
-  // by default; [] intentionally selects none.
+  // Exact model-visible OpenGeni selection. The default omits connector-wide
+  // tools; [] intentionally selects none.
   firstPartyMcpTools: z.array(FirstPartyMcpToolName),
   // Per-session third-party MCP servers, metadata only. Credential values are
   // write-only and never appear here.
@@ -6155,6 +6297,7 @@ export const ToolAuthNeededPayload = z.object({
     "expired",
     "insufficient_scope",
     "refresh_failed",
+    "personal_authority_unavailable",
     "unsupported_auth",
     "resource_scope_unavailable",
   ]),
@@ -7948,7 +8091,8 @@ export const CreateSessionRequest = withVariableSetIdAlias({
   // rejected; creation never silently expands a child beyond that set.
   firstPartyMcpPermissions: z.array(Permission).optional(),
   // Exact model-visible selection from the broad first-party OpenGeni MCP
-  // catalog. Omission selects the full catalog; [] intentionally exposes none.
+  // catalog. Omission selects the safe non-connector default; [] intentionally
+  // exposes none.
   // This does not grant authority: every registered tool is permission-gated.
   firstPartyMcpTools: z.array(FirstPartyMcpToolName).optional(),
   // Third-party MCP servers attached only to this session. For an agent-created
@@ -9326,6 +9470,35 @@ export const ClientConfig = /* @__PURE__ */ defineModelContractSchema(() =>
     }),
     productAccessMode: ProductAccessMode,
     auth: ClientAuthConfig.default({ mode: "none" }),
+    analytics: z
+      .object({
+        consentRequired: z.boolean(),
+        providers: z.object({
+          reo: z
+            .object({
+              clientId: z
+                .string()
+                .max(128)
+                .regex(/^[A-Za-z0-9_-]+$/u),
+            })
+            .optional(),
+          posthog: z
+            .object({
+              projectKey: z.string().min(1).max(256),
+              host: z.string().url().max(2_048),
+            })
+            .optional(),
+          ga4: z
+            .object({
+              measurementId: z
+                .string()
+                .max(32)
+                .regex(/^G-[A-Z0-9]+$/u),
+            })
+            .optional(),
+        }),
+      })
+      .default({ consentRequired: true, providers: {} }),
     // Server-wide hint: does this deployment support Channel-A structured services
     // at all (P4.4). Per-session availability is negotiated on /stream-capabilities
     // (it depends on the session's pinned backend); this is the coarse on/off the
@@ -9421,3 +9594,4 @@ export * from "./secret-redaction";
 export * from "./workspace-instruction-policies";
 export * from "./workspace-state";
 export * from "./preference-registry";
+export * from "./scoped-knowledge";