@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/knowledge-entries.ts

@@ -0,0 +1,428 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { AgentLearningMode } from "./agent-learning";
+
+export const KnowledgeEntryKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["source", "fact", "decision", "requirement", "incident", "note", "group"]),
+);
+export type KnowledgeEntryKind = z.infer<typeof KnowledgeEntryKind>;
+
+export const KnowledgeEntryScope = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["organization", "workspace", "personal"]),
+);
+export type KnowledgeEntryScope = z.infer<typeof KnowledgeEntryScope>;
+
+/** Source-shaped location, not a second copy of the source body. */
+export const KnowledgeEvidenceLocation = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      page: z.number().int().positive().optional(),
+      passage: z.string().max(2048).optional(),
+      messageIds: z.array(z.string().min(1).max(1024)).max(256).optional(),
+      path: z.string().min(1).max(4096).optional(),
+      commit: z.string().min(1).max(256).optional(),
+      lineStart: z.number().int().positive().optional(),
+      lineEnd: z.number().int().positive().optional(),
+    })
+    .strict()
+    .refine(
+      (value) =>
+        value.lineEnd === undefined ||
+        (value.lineStart !== undefined && value.lineEnd >= value.lineStart),
+      "an ending line requires a starting line and cannot precede it",
+    ),
+);
+export type KnowledgeEvidenceLocation = z.infer<typeof KnowledgeEvidenceLocation>;
+
+export const KnowledgeEntryEvidence = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      entryId: z.uuid(),
+      revisionId: z.uuid(),
+      location: KnowledgeEvidenceLocation.default({}),
+      quote: z.string().optional(),
+    })
+    .strict(),
+);
+export type KnowledgeEntryEvidence = z.infer<typeof KnowledgeEntryEvidence>;
+
+export const KnowledgeEntrySource = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      kind: z.enum([
+        "file",
+        "slack",
+        "conversation",
+        "repository",
+        "web",
+        "connector",
+        "manual",
+        "task_note",
+      ]),
+      noteId: z.uuid().optional(),
+      fileId: z.uuid().optional(),
+      documentId: z.uuid().optional(),
+      sessionId: z.uuid().optional(),
+      uri: z.string().min(1).max(8192).optional(),
+      externalId: z.string().min(1).max(2048).optional(),
+      version: z.string().min(1).max(2048).optional(),
+      capturedAt: z.string().datetime({ offset: true }).optional(),
+      retention: z.enum(["full_text", "passages", "reference"]).optional(),
+      /** Supporting evidence stays retrievable by ID without entering default discovery. */
+      purpose: z.enum(["evidence", "reference"]).optional(),
+    })
+    .strict(),
+);
+export type KnowledgeEntrySource = z.infer<typeof KnowledgeEntrySource>;
+
+export const KnowledgeEntryRelationship = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      entryId: z.uuid(),
+      relation: z.enum(["related_to", "depends_on", "applies_to", "conflicts_with", "supersedes"]),
+    })
+    .strict(),
+);
+export type KnowledgeEntryRelationship = z.infer<typeof KnowledgeEntryRelationship>;
+
+export const KnowledgeEntryContent = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      title: z.string().min(1),
+      kind: KnowledgeEntryKind,
+      // Exact accepted content. Request admission and paginated reads own size;
+      // source text is not truncated to the former 4,000-character Memory cap.
+      content: z.string(),
+      source: KnowledgeEntrySource.optional(),
+      evidence: z.array(KnowledgeEntryEvidence).max(256).default([]),
+      groupIds: z.array(z.uuid()).max(256).default([]),
+      relationships: z.array(KnowledgeEntryRelationship).max(256).default([]),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      if (value.kind !== "group" && value.kind !== "source" && !value.content.trim()) {
+        context.addIssue({
+          code: "custom",
+          path: ["content"],
+          message: "knowledge content is empty",
+        });
+      }
+      if (value.kind === "source" && !value.source) {
+        context.addIssue({
+          code: "custom",
+          path: ["source"],
+          message: "source entries require source identity",
+        });
+      }
+      if (new Set(value.groupIds).size !== value.groupIds.length) {
+        context.addIssue({
+          code: "custom",
+          path: ["groupIds"],
+          message: "group membership contains duplicate IDs",
+        });
+      }
+    }),
+);
+export type KnowledgeEntryContent = z.infer<typeof KnowledgeEntryContent>;
+/** Historical relationships are lossless. Admission limits apply to new writes. */
+export const StoredKnowledgeEntryContent = /* @__PURE__ */ defineSchema(() =>
+  KnowledgeEntryContent.safeExtend({
+    evidence: z.array(KnowledgeEntryEvidence).default([]),
+    groupIds: z.array(z.uuid()).default([]),
+    relationships: z.array(KnowledgeEntryRelationship).default([]),
+  }),
+);
+
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+/**
+ * Omit on create: the host derives the entry id from the operation, so an exact
+ * retry replays the same entry. Required to correct an existing entry.
+ */
+const KnowledgeWriteEntryId = /* @__PURE__ */ defineSchema(() =>
+  z
+    .uuid()
+    .refine((value) => value !== NIL_UUID, {
+      message: "entryId must be a real entry id; omit it to create a new entry",
+    })
+    .optional(),
+);
+
+/** Scope identity and agent policy are resolved by the host, never supplied by the model. */
+export const KnowledgeEntrySaveRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      entryId: KnowledgeWriteEntryId,
+      expectedVersion: z.number().int().nonnegative(),
+      scope: KnowledgeEntryScope.optional(),
+      entry: KnowledgeEntryContent.safeExtend({ title: z.string().min(1).max(1024) }),
+    })
+    .strict(),
+);
+export type KnowledgeEntrySaveRequest = z.input<typeof KnowledgeEntrySaveRequest>;
+
+export const KnowledgeTaskNotePromotionRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      entryId: KnowledgeWriteEntryId,
+      expectedVersion: z.literal(0),
+      noteId: z.uuid(),
+      expectedNoteVersion: z.literal(1),
+      title: z.string().min(1).max(1024),
+      groupIds: z.array(z.uuid()).max(256).default([]),
+    })
+    .strict(),
+);
+export type KnowledgeTaskNotePromotionRequest = z.input<typeof KnowledgeTaskNotePromotionRequest>;
+
+export const KnowledgeEntryReviewRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      entryId: z.uuid(),
+      revisionId: z.uuid(),
+      expectedVersion: z.number().int().positive(),
+      decision: z.enum(["approve", "reject"]),
+      entry: KnowledgeEntryContent.safeExtend({ title: z.string().min(1).max(1024) }).optional(),
+    })
+    .strict()
+    .refine(
+      (value) => !value.entry || value.decision === "approve",
+      "Only approval can include an edited entry",
+    ),
+);
+export type KnowledgeEntryReviewRequest = z.input<typeof KnowledgeEntryReviewRequest>;
+
+export const KnowledgeEntryBatchReviewRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      entries: z.array(KnowledgeEntryReviewRequest).min(1).max(100),
+    })
+    .strict()
+    .refine(
+      (value) => new Set(value.entries.map((entry) => entry.entryId)).size === value.entries.length,
+      "A review batch cannot repeat an entry",
+    ),
+);
+export type KnowledgeEntryBatchReviewRequest = z.input<typeof KnowledgeEntryBatchReviewRequest>;
+
+export const KnowledgeEntryRestoreRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      entryId: z.uuid(),
+      revisionId: z.uuid(),
+      expectedVersion: z.number().int().positive(),
+    })
+    .strict(),
+);
+export type KnowledgeEntryRestoreRequest = z.infer<typeof KnowledgeEntryRestoreRequest>;
+
+export const KnowledgeEntryWriteReceipt = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      entryId: z.uuid(),
+      revisionId: z.uuid(),
+      version: z.number().int().positive(),
+      outcome: z.enum(["published", "pending", "rejected", "archived"]),
+      reviewBatchId: z.uuid().nullable(),
+      replayed: z.boolean(),
+    })
+    .strict(),
+);
+export type KnowledgeEntryWriteReceipt = z.infer<typeof KnowledgeEntryWriteReceipt>;
+
+export const KnowledgeFilePreparationResult = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("status", [
+    z
+      .object({
+        status: z.literal("retained"),
+        fileId: z.uuid(),
+        filename: z.string(),
+        receipt: KnowledgeEntryWriteReceipt,
+      })
+      .strict(),
+    z.object({ status: z.literal("disabled"), fileId: z.uuid() }).strict(),
+  ]),
+);
+export type KnowledgeFilePreparationResult = z.infer<typeof KnowledgeFilePreparationResult>;
+
+export const KnowledgeEntryRevision = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.uuid(),
+      entryId: z.uuid(),
+      number: z.number().int().positive(),
+      change: z.enum(["upsert", "archive"]),
+      entry: StoredKnowledgeEntryContent,
+      previousRevisionId: z.uuid().nullable(),
+      restoredFromRevisionId: z.uuid().nullable(),
+      createdAt: z.string().datetime({ offset: true }),
+      createdBySessionId: z.uuid().nullable(),
+      reviewBatchId: z.uuid().nullable(),
+      outcome: z.enum(["published", "pending", "rejected", "superseded"]),
+    })
+    .strict(),
+);
+export type KnowledgeEntryRevision = z.infer<typeof KnowledgeEntryRevision>;
+
+/** Search/index progress is independent of saved source and keyword access. */
+export const KnowledgeIndexStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "saved",
+    "queued",
+    "indexing",
+    "awaiting_funding",
+    "indexed",
+    "source_unavailable",
+    "provider_failed",
+  ]),
+);
+export type KnowledgeIndexStatus = z.infer<typeof KnowledgeIndexStatus>;
+
+/** Private owner IDs are not part of a content-discovery projection. */
+export const KnowledgeEntryRecord = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.uuid(),
+      scope: KnowledgeEntryScope,
+      version: z.number().int().positive(),
+      publishedRevisionId: z.uuid().nullable(),
+      latestRevisionId: z.uuid(),
+      revision: KnowledgeEntryRevision,
+      archived: z.boolean(),
+      createdAt: z.string().datetime({ offset: true }),
+      updatedAt: z.string().datetime({ offset: true }),
+      indexStatus: KnowledgeIndexStatus.optional(),
+    })
+    .strict(),
+);
+export type KnowledgeEntryRecord = z.infer<typeof KnowledgeEntryRecord>;
+
+export const KnowledgeEntryListRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      query: z.string().max(4096).optional(),
+      mode: z.enum(["hybrid", "keyword", "vector"]).default("hybrid"),
+      scope: KnowledgeEntryScope.optional(),
+      groupId: z.uuid().optional(),
+      /** Top-level entries with no visible collection in the selected scope. */
+      rootOnly: z.boolean().optional(),
+      fileId: z.uuid().optional(),
+      /** Include supporting sources in published discovery; never changes access. */
+      includeEvidence: z.boolean().optional(),
+      kind: KnowledgeEntryKind.optional(),
+      /** Inclusive original entry creation time; revisions and updates do not reset it. */
+      createdSince: z.string().datetime({ offset: true }).optional(),
+      view: z.enum(["published", "needs_review", "archived", "rejected"]).default("published"),
+      sessionId: z.uuid().optional(),
+      reviewBatchId: z.uuid().optional(),
+      cursor: z.string().min(1).max(2048).optional(),
+      limit: z.number().int().positive().max(50).default(20),
+    })
+    .strict(),
+);
+export type KnowledgeEntryListRequest = z.input<typeof KnowledgeEntryListRequest>;
+
+/** Lists never transfer whole source texts or evidence quotations. */
+export const KnowledgeEntrySummary = /* @__PURE__ */ defineSchema(() =>
+  KnowledgeEntryRecord.omit({ revision: true }).extend({
+    score: z.number().finite().optional(),
+    excerpts: z
+      .array(
+        z.object({
+          field: z.enum(["title", "content"]),
+          start: z.number().int().nonnegative(),
+          end: z.number().int().nonnegative(),
+          text: z.string(),
+        }),
+      )
+      .default([]),
+    revision: KnowledgeEntryRevision.omit({ entry: true }).extend({
+      title: z.string(),
+      kind: KnowledgeEntryKind,
+      preview: z.string(),
+      groupIds: z.array(z.uuid()),
+      sourceKind: KnowledgeEntrySource.shape.kind.nullable(),
+    }),
+  }),
+);
+export type KnowledgeEntrySummary = z.infer<typeof KnowledgeEntrySummary>;
+
+export const KnowledgeEntryListResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    entries: z.array(KnowledgeEntrySummary),
+    nextCursor: z.string().nullable(),
+    searchMode: z.enum(["keyword", "hybrid", "vector"]).optional(),
+    fallbackReason: z
+      .enum([
+        "awaiting_funding",
+        "credits_disabled",
+        "quota",
+        "provider_unavailable",
+        "query_limit",
+      ])
+      .optional(),
+  }),
+);
+export type KnowledgeEntryListResponse = z.infer<typeof KnowledgeEntryListResponse>;
+
+export const KnowledgeReviewBatch = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: z.uuid(),
+    sessionId: z.uuid().nullable(),
+    scheduledTaskId: z.uuid().nullable(),
+    scheduledTaskRunId: z.uuid().nullable(),
+    title: z.string().nullable(),
+    scope: KnowledgeEntryScope,
+    pendingCount: z.number().int().nonnegative(),
+    createdAt: z.string().datetime({ offset: true }),
+  }),
+);
+export type KnowledgeReviewBatch = z.infer<typeof KnowledgeReviewBatch>;
+
+export const KnowledgeReviewBatchListRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      scope: KnowledgeEntryScope.optional(),
+      cursor: z.string().min(1).max(2048).optional(),
+      limit: z.number().int().positive().max(50).default(20),
+    })
+    .strict(),
+);
+export type KnowledgeReviewBatchListRequest = z.input<typeof KnowledgeReviewBatchListRequest>;
+export const KnowledgeReviewBatchListResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    batches: z.array(KnowledgeReviewBatch),
+    nextCursor: z.string().nullable(),
+  }),
+);
+export type KnowledgeReviewBatchListResponse = z.infer<typeof KnowledgeReviewBatchListResponse>;
+
+/** All policy outcomes are nonblocking; Off refuses authoring, not task execution. */
+export function knowledgeWriteDisposition(mode: z.infer<typeof AgentLearningMode>) {
+  switch (AgentLearningMode.parse(mode)) {
+    case "automatic":
+      return "published" as const;
+    case "review_first":
+      return "pending" as const;
+    case "off":
+      return "disabled" as const;
+  }
+}
+
+export const KnowledgeOriginalFileDownload = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      url: z.string().url(),
+      expiresAt: z.string(),
+      fileId: z.uuid(),
+      filename: z.string(),
+      contentType: z.string(),
+      sizeBytes: z.number().int().nonnegative(),
+    })
+    .strict(),
+);
+export type KnowledgeOriginalFileDownload = z.infer<typeof KnowledgeOriginalFileDownload>;

package/src/knowledge-preparation.ts

@@ -0,0 +1,57 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { KnowledgeEntryListResponse, KnowledgeEntryScope } from "./knowledge-entries";
+
+/** Read-only discovery before a model decides whether and where to save. */
+export const KnowledgeSavePreparationRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      query: z.string().trim().min(1).max(4096),
+      limit: z.number().int().positive().max(20).default(8),
+      collectionCursors: z
+        .object({
+          published: z.string().min(1).max(2048).nullable(),
+          needs_review: z.string().min(1).max(2048).nullable(),
+        })
+        .strict()
+        .optional(),
+    })
+    .strict(),
+);
+export type KnowledgeSavePreparationRequest = z.input<typeof KnowledgeSavePreparationRequest>;
+
+export const KnowledgeCollectionDescriptor = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.uuid(),
+      revisionId: z.uuid(),
+      version: z.number().int().positive(),
+      scope: KnowledgeEntryScope,
+      view: z.enum(["published", "needs_review"]),
+      title: z.string(),
+      description: z.string(),
+      descriptionTruncated: z.boolean(),
+      parentIds: z.array(z.uuid()),
+    })
+    .strict(),
+);
+
+export const KnowledgeSavePreparationResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      collections: z.object({
+        entries: z.array(KnowledgeCollectionDescriptor),
+        complete: z.boolean(),
+        nextCursors: z.object({
+          published: z.string().nullable(),
+          needs_review: z.string().nullable(),
+        }),
+      }),
+      matches: z.object({
+        published: KnowledgeEntryListResponse,
+        needs_review: KnowledgeEntryListResponse,
+      }),
+    })
+    .strict(),
+);
+export type KnowledgeSavePreparationResponse = z.infer<typeof KnowledgeSavePreparationResponse>;