@opengeni/contracts 0.50.0 → 1.0.0

package/src/knowledge-entries.ts

@@ -0,0 +1,375 @@
+import { z } from "zod";
+import { AgentLearningMode } from "./agent-learning";
+
+export const KnowledgeEntryKind = z.enum([
+  "source",
+  "fact",
+  "decision",
+  "requirement",
+  "incident",
+  "note",
+  "group",
+]);
+export type KnowledgeEntryKind = z.infer<typeof KnowledgeEntryKind>;
+
+export const KnowledgeEntryScope = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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(),
+    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 = 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 = z.object({
+  entries: z.array(KnowledgeEntrySummary),
+  nextCursor: z.string().nullable(),
+  searchMode: z.enum(["keyword", "hybrid", "vector"]).optional(),
+  fallbackReason: z
+    .enum(["awaiting_funding", "quota", "provider_unavailable", "query_limit"])
+    .optional(),
+});
+export type KnowledgeEntryListResponse = z.infer<typeof KnowledgeEntryListResponse>;
+
+export const KnowledgeReviewBatch = 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 = 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 = 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 = 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,50 @@
+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 = 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 = 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 = 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>;

package/src/knowledge.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 export const KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS = 1_024;
 export const KNOWLEDGE_BROWSE_DEFAULT_LIMIT = 20;
 export const KNOWLEDGE_BROWSE_MAX_LIMIT = 50;
+export const KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES = 64 * 1_024;
 export const KNOWLEDGE_TITLE_MAX_BYTES = 1_024;
 export const KNOWLEDGE_BODY_MAX_BYTES = 16 * 1_024;
 export const KNOWLEDGE_SUMMARY_MAX_BYTES = 4 * 1_024;
@@ -13,6 +14,16 @@ export const KNOWLEDGE_METADATA_MAX_ITEMS = 64;
 export const KNOWLEDGE_METADATA_MAX_DEPTH = 4;
 export const KNOWLEDGE_SOURCE_STRING_MAX_BYTES = 2_048;
 export const KNOWLEDGE_SOURCE_URI_MAX_BYTES = 8_192;
+export const KNOWLEDGE_SEARCH_MAX_RESULTS = 50;
+export const KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES = 64 * 1_024;
+export const KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN = 4;
+export const KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS = 200;
+// Cosine similarity for unrelated embeddings clusters around 0.5 after the
+// distance conversion used by Documents. Keyword search already excludes
+// non-matches in SQL, but a small normalized floor removes incidental hits.
+export const KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE = 0.52;
+export const KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE = 0.01;
+export const KNOWLEDGE_QUERY_MAX_BYTES = 4 * 1_024;
 
 const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
 const boundedUtf8 = (maxBytes: number) =>
@@ -102,6 +113,60 @@ export const KnowledgeSource = z.object({
 });
 export type KnowledgeSource = z.infer<typeof KnowledgeSource>;
 
+export const KnowledgeSearchRequest = z
+  .object({
+    query: boundedUtf8(KNOWLEDGE_QUERY_MAX_BYTES).pipe(z.string().min(1)),
+    baseIds: z.array(z.string().uuid()).max(50).optional(),
+    mode: z.enum(["hybrid", "vector", "keyword"]).optional(),
+    sourceKinds: z.array(KnowledgeSource.shape.kind).max(8).optional(),
+    authorityKinds: z.array(KnowledgeAuthority.shape.kind).max(3).optional(),
+    aclTags: z
+      .array(boundedUtf8(KNOWLEDGE_TOPIC_MAX_BYTES).pipe(z.string().min(1)))
+      .max(64)
+      .optional(),
+    limit: z.number().int().positive().max(KNOWLEDGE_SEARCH_MAX_RESULTS).default(5),
+  })
+  .strict();
+export type KnowledgeSearchRequest = z.input<typeof KnowledgeSearchRequest>;
+
+export const KnowledgeBrowseRequest = z
+  .object({
+    parentId: KnowledgeRecordId.optional(),
+    topic: boundedUtf8(KNOWLEDGE_TOPIC_MAX_BYTES).pipe(z.string().min(1)).optional(),
+    sourceKinds: z.array(KnowledgeSource.shape.kind).max(8).optional(),
+    cursor: z.string().min(1).max(KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS).optional(),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .max(KNOWLEDGE_BROWSE_MAX_LIMIT)
+      .default(KNOWLEDGE_BROWSE_DEFAULT_LIMIT),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.parentId && (value.topic || (value.sourceKinds?.length ?? 0) > 0)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "document contents do not accept topic or source filters",
+      });
+    }
+  });
+export type KnowledgeBrowseRequest = z.input<typeof KnowledgeBrowseRequest>;
+
+export const KnowledgeProviderCitation = z.object({
+  provider: z.literal("google_drive"),
+  externalObjectId: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES),
+  providerRevision: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES).nullable(),
+  sourceVersion: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES),
+  driveId: boundedUtf8(KNOWLEDGE_SOURCE_STRING_MAX_BYTES).nullable(),
+  deepLink: boundedUtf8(KNOWLEDGE_SOURCE_URI_MAX_BYTES).pipe(z.string().min(1)).nullable(),
+  aclRevision: z.string().regex(/^[0-9a-f]{64}$/u),
+  authorizationObservedAt: z.string().datetime({ offset: true }),
+  authorizationExpiresAt: z.string().datetime({ offset: true }),
+  reauthorizedAt: z.string().datetime({ offset: true }),
+});
+export type KnowledgeProviderCitation = z.infer<typeof KnowledgeProviderCitation>;
+
 export const KnowledgeLinkTarget = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("knowledge"),
@@ -144,6 +209,7 @@ export const KnowledgeRecord = z.object({
   provenance: z.object({
     source: KnowledgeSource,
     indexedAt: z.string(),
+    citation: KnowledgeProviderCitation.nullable().optional(),
   }),
   lifecycle: z.object({
     state: z.literal("active"),
@@ -171,9 +237,10 @@ export const KnowledgeRecord = z.object({
           "provenance.source.title",
           "provenance.source.author",
           "provenance.source.version",
+          "provenance.citation",
         ]),
       )
-      .max(10),
+      .max(11),
   }),
 });
 export type KnowledgeRecord = z.infer<typeof KnowledgeRecord>;
@@ -181,16 +248,59 @@ export type KnowledgeRecord = z.infer<typeof KnowledgeRecord>;
 export const KnowledgeSearchResult = z.object({
   record: KnowledgeRecord,
   retrieval: z.object({
-    score: z.number(),
+    /** Final bounded ordering score after the documented quality adjustment. */
+    score: z.number().min(0).max(1),
+    /** Semantic score before the quality adjustment. */
+    semanticScore: z.number().min(0).max(1),
     matchType: z.enum(["hybrid", "vector", "keyword"]),
-    vectorScore: z.number().nullable(),
-    keywordScore: z.number().nullable(),
+    vectorScore: z.number().min(0).max(1).nullable(),
+    keywordScore: z.number().min(0).max(1).nullable(),
+    relevanceSignals: z
+      .array(z.enum(["vector", "keyword"]))
+      .min(1)
+      .max(2),
+    freshness: z.enum(["current", "aging", "stale"]),
+    qualityAdjustment: z.number().min(0).max(1),
+    duplicateCount: z.number().int().nonnegative(),
   }),
 });
 export type KnowledgeSearchResult = z.infer<typeof KnowledgeSearchResult>;
 
 export const KnowledgeSearchResponse = z.object({
-  results: z.array(KnowledgeSearchResult),
+  results: z.array(KnowledgeSearchResult).max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+  selection: z.object({
+    relevanceFloor: z.object({
+      policy: z.literal("any_signal"),
+      vectorScore: z.literal(KNOWLEDGE_SEARCH_MIN_VECTOR_SCORE),
+      keywordScore: z.literal(KNOWLEDGE_SEARCH_MIN_KEYWORD_SCORE),
+    }),
+    dedupe: z.object({
+      policy: z.literal("exact_textual_content"),
+    }),
+    candidates: z.object({
+      ranked: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      rechecked: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      omittedOnRecheck: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+    }),
+    omitted: z.object({
+      belowRelevanceFloor: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_FLOOR_OMISSIONS),
+      asDuplicate: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      forLimit: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      forResponseBudget: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESULTS),
+    }),
+    budget: z.object({
+      maxResults: z.literal(KNOWLEDGE_SEARCH_MAX_RESULTS),
+      maxResponseBytes: z.literal(KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES),
+      responseBytes: z.number().int().nonnegative().max(KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES),
+      tokenEstimateBytesPerToken: z.literal(KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN),
+      estimatedTokens: z.number().int().nonnegative(),
+      maxEstimatedTokens: z.literal(
+        Math.ceil(
+          KNOWLEDGE_SEARCH_MAX_RESPONSE_BYTES / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN,
+        ),
+      ),
+    }),
+  }),
 });
 export type KnowledgeSearchResponse = z.infer<typeof KnowledgeSearchResponse>;
 
@@ -200,8 +310,26 @@ export const KnowledgeGetResponse = z.object({
 export type KnowledgeGetResponse = z.infer<typeof KnowledgeGetResponse>;
 
 export const KnowledgeBrowseResponse = z.object({
-  records: z.array(KnowledgeRecord),
+  records: z.array(KnowledgeRecord).max(KNOWLEDGE_BROWSE_MAX_LIMIT),
   nextCursor: z.string().min(1).max(KNOWLEDGE_BROWSE_CURSOR_MAX_CHARS).nullable(),
   hasMore: z.boolean(),
+  selection: z.object({
+    omitted: z.object({
+      forResponseBudget: z.number().int().nonnegative().max(KNOWLEDGE_BROWSE_MAX_LIMIT),
+    }),
+    compactedRecordCount: z.number().int().nonnegative().max(1),
+    budget: z.object({
+      maxResults: z.literal(KNOWLEDGE_BROWSE_MAX_LIMIT),
+      maxResponseBytes: z.literal(KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES),
+      responseBytes: z.number().int().nonnegative().max(KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES),
+      tokenEstimateBytesPerToken: z.literal(KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN),
+      estimatedTokens: z.number().int().nonnegative(),
+      maxEstimatedTokens: z.literal(
+        Math.ceil(
+          KNOWLEDGE_BROWSE_MAX_RESPONSE_BYTES / KNOWLEDGE_SEARCH_TOKEN_ESTIMATE_BYTES_PER_TOKEN,
+        ),
+      ),
+    }),
+  }),
 });
 export type KnowledgeBrowseResponse = z.infer<typeof KnowledgeBrowseResponse>;