@opengeni/contracts 0.28.1 → 0.31.0

package/src/index.ts

@@ -2548,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;
@@ -2575,6 +2615,7 @@ export type McpCredentialsRequest = {
 
 export type McpCredentialAuthNeededReason =
   | CredentialAuthNeededReason
+  | "personal_authority_unavailable"
   | "unsupported_auth"
   | "resource_scope_unavailable";
 
@@ -4021,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(),
@@ -4508,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
@@ -4875,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 */
@@ -5117,43 +5165,83 @@ export const CapabilityPack = z.preprocess(
     }
     return record;
   },
-  z.object({
-    id: z.string().min(1),
-    name: z.string().min(1),
-    description: z.string().min(1),
-    role: z.string().min(1),
-    category: z.string().min(1),
-    version: z.string().min(1),
-    // Container image ref (digest-pinned recommended) the pack's sessions run
-    // in. At most one enabled pack per workspace may declare one; with none,
-    // sessions use the deployment-wide image settings.
-    sandboxImage: z.string().trim().min(1).max(512).optional(),
-    // Skills delivered into the sandbox skill index when the pack is enabled.
-    skills: z
-      .array(CapabilityPackSkill)
-      .max(32)
-      .superRefine((skills, ctx) => {
-        const seen = new Set<string>();
-        skills.forEach((skill, index) => {
-          const key = skill.name.toLowerCase();
-          if (seen.has(key)) {
-            ctx.addIssue({
-              code: "custom",
-              message: `duplicate pack skill name: ${skill.name}`,
-              path: [index, "name"],
-            });
-          }
-          seen.add(key);
+  z
+    .object({
+      id: z.string().min(1),
+      name: z.string().min(1),
+      description: z.string().min(1),
+      role: z.string().min(1),
+      category: z.string().min(1),
+      version: z.string().min(1),
+      // Container image ref (digest-pinned recommended) the pack's sessions run
+      // in. At most one enabled pack per workspace may declare one; with none,
+      // sessions use the deployment-wide image settings.
+      sandboxImage: z.string().trim().min(1).max(512).optional(),
+      // Optional provider-native immutable identities for the exact logical
+      // sandboxImage above. These avoid re-importing a private registry image on
+      // every provider while preserving sandboxImage as the cross-provider image
+      // provenance and lease-conflict identity.
+      sandboxProviderImages: z
+        .object({
+          modal: z
+            .object({
+              imageId: z
+                .string()
+                .trim()
+                .regex(/^im-[A-Za-z0-9]{22}$/),
+            })
+            .strict()
+            .optional(),
+        })
+        .strict()
+        .optional(),
+      // Skills delivered into the sandbox skill index when the pack is enabled.
+      skills: z
+        .array(CapabilityPackSkill)
+        .max(32)
+        .superRefine((skills, ctx) => {
+          const seen = new Set<string>();
+          skills.forEach((skill, index) => {
+            const key = skill.name.toLowerCase();
+            if (seen.has(key)) {
+              ctx.addIssue({
+                code: "custom",
+                message: `duplicate pack skill name: ${skill.name}`,
+                path: [index, "name"],
+              });
+            }
+            seen.add(key);
+          });
+        })
+        .default([]),
+      tools: z.array(ToolRef).default([]),
+      connectors: z.array(CapabilityPackConnector).default([]),
+      knowledge: z.array(CapabilityPackKnowledge).default([]),
+      scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
+      variableSet: CapabilityPackVariableSet.optional(),
+      metadata: z.record(z.string(), z.unknown()).default({}),
+    })
+    .superRefine((pack, ctx) => {
+      if (!pack.sandboxProviderImages?.modal) {
+        return;
+      }
+      if (!pack.sandboxImage) {
+        ctx.addIssue({
+          code: "custom",
+          message: "sandboxProviderImages.modal requires sandboxImage",
+          path: ["sandboxProviderImages", "modal"],
         });
-      })
-      .default([]),
-    tools: z.array(ToolRef).default([]),
-    connectors: z.array(CapabilityPackConnector).default([]),
-    knowledge: z.array(CapabilityPackKnowledge).default([]),
-    scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
-    variableSet: CapabilityPackVariableSet.optional(),
-    metadata: z.record(z.string(), z.unknown()).default({}),
-  }),
+        return;
+      }
+      if (!/@sha256:[0-9a-f]{64}$/i.test(pack.sandboxImage)) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "sandboxProviderImages.modal requires sandboxImage to be pinned by an OCI sha256 digest",
+          path: ["sandboxImage"],
+        });
+      }
+    }),
 );
 export type CapabilityPack = z.infer<typeof CapabilityPack>;
 
@@ -5397,9 +5485,14 @@ function compareDescending(left: number | string, right: number | string): numbe
 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([]),
@@ -5449,6 +5542,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),
@@ -6243,6 +6337,7 @@ export const ToolAuthNeededPayload = z.object({
     "expired",
     "insufficient_scope",
     "refresh_failed",
+    "personal_authority_unavailable",
     "unsupported_auth",
     "resource_scope_unavailable",
   ]),
@@ -9539,3 +9634,4 @@ export * from "./secret-redaction";
 export * from "./workspace-instruction-policies";
 export * from "./workspace-state";
 export * from "./preference-registry";
+export * from "./scoped-knowledge";

package/src/scoped-knowledge.ts

@@ -0,0 +1,216 @@
+import { z } from "zod";
+
+/** Tenant scope for normalized knowledge and source provenance. */
+export const ScopedKnowledgeScopeKind = z.enum(["organization", "workspace", "personal"]);
+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 const ScopedKnowledgeActorKind = z.enum(["human", "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 const KnowledgeLifecycleState = z.enum(["active", "deleted", "revoked"]);
+export type KnowledgeLifecycleState = z.infer<typeof KnowledgeLifecycleState>;
+
+export const KnowledgeLifecycleEventType = z.enum([
+  "deleted",
+  "revoked",
+  "restored",
+  "acl_changed",
+  "sync_succeeded",
+  "sync_failed",
+  "object_version_added",
+]);
+export type KnowledgeLifecycleEventType = z.infer<typeof KnowledgeLifecycleEventType>;
+
+export const KnowledgeSyncRunState = z.enum(["started", "succeeded", "failed"]);
+export type KnowledgeSyncRunState = z.infer<typeof KnowledgeSyncRunState>;
+
+export const KnowledgeClaimOrigin = z.enum(["explicit", "inferred"]);
+export type KnowledgeClaimOrigin = z.infer<typeof KnowledgeClaimOrigin>;
+
+export const KnowledgeClaimRelationType = z.enum(["supersedes", "conflicts_with"]);
+export type KnowledgeClaimRelationType = z.infer<typeof KnowledgeClaimRelationType>;
+
+export const KnowledgeClaimEvidencePolarity = z.enum(["supports", "contradicts"]);
+export type KnowledgeClaimEvidencePolarity = z.infer<typeof KnowledgeClaimEvidencePolarity>;
+
+export const KnowledgeClaimReviewState = z.enum(["proposed", "approved", "rejected", "revoked"]);
+export type KnowledgeClaimReviewState = z.infer<typeof KnowledgeClaimReviewState>;
+
+export const KnowledgeFactObjectKind = z.enum([
+  "entity",
+  "text",
+  "number",
+  "boolean",
+  "json",
+  "timestamp",
+]);
+export type KnowledgeFactObjectKind = z.infer<typeof KnowledgeFactObjectKind>;
+
+export const KnowledgeChangeProposalTargetKind = z.enum(["instruction_policy", "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;
+};