@native-knowledge/knowledge-sdk 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/internal/serving-contracts/agent-catalog.js

@@ -0,0 +1,56 @@
+const row = (category, title, description, readOnly, terms) => ({ category, title, description, readOnly, terms });
+export const agentCatalog = {
+    knowledge_resource_search_body: row('materials', 'Search document body / 搜索正文', 'Search indexed native UTF-8 text and JSON string passages with hash-bound exact citations; coverage is partial.', true, ['body', 'body search', 'full text', 'passage', 'quote', 'citation', '正文', '搜索正文', '正文检索', '全文', '段落', '引用', '原句']),
+    knowledge_resource_read_passage: row('materials', 'Verify exact citation / 核验准确引用', 'Re-read canonical material and verify an exact quote, content hash, JSON pointer and UTF-16 offsets under current authority.', true, ['verify', 'citation', 'quote', '核验', '引用', '出处']),
+    knowledge_resource_search: row('materials', 'Search retained material / 搜索资料', 'Search authorized indexed titles and descriptions; consult index status for coverage.', true, ['search', 'find', '查找', '搜索', '检索', '资料', '文档']),
+    knowledge_resource_list: row('materials', 'Browse material / 浏览资料', 'Page authorized material without requiring a search phrase.', true, ['list', 'browse', '列出', '浏览', '资料', '文档']),
+    knowledge_resource_describe: row('materials', 'Inspect material / 查看资料信息', 'Inspect one exact ref and its access decision before reading.', true, ['describe', 'metadata', '详情', '元数据', '资料']),
+    knowledge_resource_read: row('materials', 'Read original / 读取原文', 'Read a bounded original or obtain its authorized download location.', true, ['read', 'original', 'download', '读取', '原文', '下载', '文件']),
+    knowledge_resource_capabilities: row('materials', 'Inspect representations / 查看可读表示', 'Inspect available content representations and access boundaries.', true, ['representation', 'capabilities', '表示', '格式', '能力']),
+    knowledge_resource_media: row('materials', 'Browse media / 查看图片附件', 'Page images, video and other media of an exact document.', true, ['media', 'image', 'video', '图片', '视频', '媒体', '附件']),
+    knowledge_resource_counts: row('materials', 'Count material / 统计资料', 'Read bounded resource counts with a continuation when needed.', true, ['count', 'statistics', '统计', '数量']),
+    knowledge_resource_window: row('materials', 'Capture sync window / 获取同步窗口', 'Capture the retained directory change window before synchronization.', true, ['sync', 'window', '同步', '窗口']),
+    knowledge_resource_changes: row('materials', 'Read changes / 查看资料变更', 'Page directory changes within the captured synchronization window.', true, ['changes', 'updates', '变更', '同步', '更新']),
+    knowledge_resource_index_status: row('runtime', 'Inspect search index / 查看索引状态', 'Inspect actual index coverage; registration does not imply searchable content.', true, ['index', 'searchable', '索引', '搜不到']),
+    tenant_material_submit: row('materials', 'Save original / 保存原件', 'Register author-provided bytes and provenance; does not collect websites.', false, ['save', 'upload', 'submit', '保存', '上传', '原件']),
+    tenant_artifact_draft: row('governance', 'Create draft / 创建草稿', 'Persist an authored draft with its explicit provenance.', false, ['draft', 'write', '草稿', '撰写']),
+    tenant_knowledge_compose: row('governance', 'Compose knowledge / 合成知识', 'Compose from exact retained source refs without asserting review approval.', false, ['compose', 'synthesize', '合成', '研究', '知识']),
+    tenant_knowledge_review: row('governance', 'Record review / 记录审核', 'Record an actual independent review and explicit decision.', false, ['review', 'audit', '审核', '审查']),
+    tenant_artifact_promote: row('governance', 'Advance lifecycle / 推进审核状态', 'Apply an explicit target status; approval requires its independent scope and review.', false, ['promote', 'approve', '审批', '批准', '状态']),
+    tenant_snapshot_declare: row('governance', 'Declare snapshot / 声明快照', 'Declare retained snapshot currentness without pretending to reobserve the source.', false, ['declare', 'freshness', '快照', '声明', '时效']),
+    tenant_snapshot_status: row('governance', 'Inspect snapshot / 查看快照状态', 'Read currentness of one exact retained resource.', true, ['snapshot', 'currentness', '快照', '时效', '新鲜度']),
+    tenant_workflow_plan: row('governance', 'Plan next step / 规划下一步', 'Use actual persisted facts to identify blockers, missing inputs and allowed next actions.', true, ['plan', 'next', 'blocker', '下一步', '怎么办', '规划', '阻塞', '发布']),
+    tenant_workflow_advance: row('governance', 'Execute plan action / 执行计划动作', 'Execute one explicitly chosen lifecycle action; never invent a PASS review.', false, ['advance', 'transition', '推进', '提交审核', '完成审核']),
+    tenant_knowledge_read: row('governance', 'Read reviewed knowledge / 读取受治理知识', 'Read reviewed Knowledge under the current consumer policy.', true, ['governed', 'reviewed', 'knowledge', '已审核', '知识', '受治理']),
+    tenant_material_share: row('sharing', 'Share material / 共享资料', 'Create an explicit authorized route to an exact resource.', false, ['share', 'route', '共享', '分享']),
+    tenant_material_revoke: row('sharing', 'Revoke sharing / 撤销共享', 'Revoke an existing sharing route explicitly.', false, ['revoke', 'unshare', '撤销', '取消共享']),
+    tenant_material_routes: row('sharing', 'Inspect sharing / 查看共享', 'Page the current Tenant sharing routes.', true, ['routes', 'sharing', '共享', '路由']),
+    tenant_source_define: row('sources', 'Define source / 定义来源', 'Register or revise explicit source semantics.', false, ['define', 'register', 'source', '定义', '登记', '来源']),
+    tenant_source_configure: row('sources', 'Configure source / 配置来源', 'Pause, enable or set an explicit refresh policy with the expected generation.', false, ['configure', 'pause', 'refresh', '配置', '暂停', '来源', '刷新']),
+    tenant_source_get: row('sources', 'Inspect source / 查看来源', 'Get an exact registered source and its current generation.', true, ['get', 'source', '查看', '来源']),
+    tenant_source_list: row('sources', 'List managed sources / 列出管理来源', 'Page source definitions under source management authority.', true, ['list', 'source', '列出', '来源']),
+    tenant_source_inventory: row('sources', 'Browse source inventory / 浏览来源清单', 'Page registered source metadata using read authority.', true, ['inventory', 'source', '来源', '清单']),
+    tenant_collection_request: row('collection', 'Request source collection / 请求采集来源', 'Persist an explicit manual collection request; Host policy still controls execution.', false, ['collect', 'request', '采集', '抓取', '手动']),
+    tenant_collection_status: row('collection', 'Inspect collection request / 查看采集请求', 'Read an exact request and its completion or failure metadata.', true, ['request', 'status', 'progress', '采集', '请求', '进度']),
+    tenant_work_queue: row('governance', 'Browse work queue / 查看待办', 'Page authorized research, draft, review and rework metadata.', true, ['queue', 'todo', 'work', '待办', '队列', '返工']),
+    tenant_project_list: row('projects', 'Browse projects / 浏览项目', 'Page explicit purpose contexts; Tenant owns the underlying material.', true, ['list', 'project', '项目', '列表']),
+    tenant_project_get: row('projects', 'Inspect project / 查看项目', 'Inspect purpose, scope and selection using separate continuations.', true, ['project', 'purpose', '项目', '目的', '范围']),
+    tenant_project_materials: row('projects', 'Browse project material / 查看项目资料', 'Page materials inside the explicitly selected project scope.', true, ['project', 'material', '项目', '资料']),
+    tenant_project_scope_set: row('projects', 'Set project scope / 修改项目范围', 'Change explicit material selection with an expected revision.', false, ['scope', 'selection', '范围', '选择']),
+    tenant_project_lifecycle_set: row('projects', 'Archive or restore project / 归档恢复项目', 'Apply explicit project lifecycle changes without deleting Tenant assets.', false, ['archive', 'restore', '归档', '恢复']),
+    tenant_runtime_status: row('runtime', 'Inspect runtime / 查看运行状态', 'Page authorized runtime metadata and actual execution blockers.', true, ['runtime', 'status', 'failure', '运行', '失败', '预算', '执行']),
+    tenant_web_collect_preview: row('collection', 'Preview website task / 预览网站采集', 'Validate a website collection intent and extraction plan before submission.', true, ['preview', 'website', 'web', '预览', '网站', '网页', '采集']),
+    tenant_web_collect_submit: row('collection', 'Submit website task / 提交网站采集', 'Submit an explicit bounded website task under current Host capabilities.', false, ['submit', 'website', 'crawl', '提交', '网站', '采集', '抓取']),
+    tenant_web_collect_status: row('collection', 'Inspect website task / 查看网站任务', 'Read lifecycle, acquisition, registration and requirements separately.', true, ['website', 'status', 'progress', '网站', '采集', '进度', '状态']),
+    tenant_web_collect_results: row('collection', 'Browse website results / 浏览网站结果', 'Page sealed result snapshots while preserving the exact job and window.', true, ['results', 'website', 'extraction', '结果', '网站', '提取']),
+    tenant_web_collect_cycles: row('collection', 'Browse observation cycles / 浏览观察周期', 'Page retained observation cycles of an exact website task.', true, ['cycles', 'observations', '周期', '观察']),
+    tenant_web_collect_control: row('collection', 'Pause resume or cancel task / 暂停恢复取消任务', 'Apply an explicit lifecycle control with the expected epoch.', false, ['pause', 'resume', 'cancel', '暂停', '恢复', '取消', '任务']),
+    tenant_web_collect_refresh: row('collection', 'Refresh website task / 刷新网站任务', 'Request one explicit new observation; replay cannot renew an old observation.', false, ['refresh', 'reobserve', '刷新', '重新观察']),
+    tenant_web_collect_read: row('collection', 'Read website result / 读取网站原件结果', 'Read an exact retained ORIGINAL, DOM or RESULT with separate read authority.', true, ['read', 'website', 'original', 'result', '读取', '网站', '原文', '结果']),
+    tenant_web_collect_index_status: row('runtime', 'Inspect website index / 查看网站索引', 'Read actual indexing status separately from successful acquisition.', true, ['website', 'index', '网站', '索引']),
+};
+export const agentCategoryTitles = { materials: 'Material discovery / 资料检索', sources: 'Source management / 来源管理', collection: 'Collection tasks / 采集任务', governance: 'Knowledge workflow / 知识工作流', sharing: 'Sharing / 共享', projects: 'Project purpose / 项目用途', runtime: 'Runtime diagnostics / 运行诊断' };
+export function recallAgentCapabilities(query, names) {
+    const text = query.normalize('NFKC').toLowerCase(), tokens = [...new Set((text.match(/[a-z0-9_]+/g) ?? []).filter(t => t.length >= 3 && !['the', 'and', 'for', 'with', 'from', 'that', 'this', 'want', 'would', 'please'].includes(t)))];
+    return names.map(name => { const card = agentCatalog[name], terms = card.terms, score = name === text ? 1000 : terms.reduce((n, term) => n + (text.includes(term) ? 2 : 0), 0) + tokens.reduce((n, t) => n + ((card.description + ' ' + card.title).toLowerCase().includes(t) ? 1 : 0), 0); return { name, score }; }).filter(item => item.score > 0).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).map(item => item.name);
+}

package/dist/internal/serving-contracts/agent-entry.js

@@ -0,0 +1,57 @@
+/** Task-first presentation over existing contracts; discovery never grants authority. */
+import { z } from 'zod';
+import { materialTenantIdSchema, resourceToolSchemas, resourceDataSchemas, resourceEnvelopeSchema } from '../contracts/index.js';
+import { tenantWebWorkflowWorkspaceToolSchemas, tenantWebWorkflowDataSchemas, tenantWebWorkflowToolSchemas, tenantWebWorkflowEnvelopeSchema, tenantWebWorkflowErrorSchema } from './tenant-web-workflow.js';
+import { tenantRuntimeWorkspaceDataSchemas, tenantRuntimeEnvelopeSchema } from './tenant-runtime.js';
+import { tenantManagementProviderBaseSchema } from './tenant-management.js';
+import { bodySearchToolSchemas, bodySearchDataSchemas, bodySearchEnvelopeSchema } from './body-search.js';
+import { agentGuidanceActionSchema, agentTaskInputSchema, agentTaskPlanSchema, agentInputHintSchema, agentGuidedFailureSchema } from './agent-guidance-shapes.js';
+const { tenant_workflow_guide: legacyGuide, ...management } = tenantWebWorkflowWorkspaceToolSchemas;
+export const agentCapabilitySchemas = { ...resourceToolSchemas, ...bodySearchToolSchemas, ...management };
+export const agentCapabilityDataSchemas = { ...resourceDataSchemas, ...bodySearchDataSchemas, ...tenantRuntimeWorkspaceDataSchemas, ...tenantWebWorkflowDataSchemas };
+// Keep the registry out of the entry schemas as well as tools/list. The predicate
+// narrows only to registered names; JSON Schema advertises a bounded identifier.
+export const agentCapabilityNameSchema = z.string().min(1).max(128).regex(/^(?:tenant_|knowledge_resource_)[a-z_]+$/).refine(name => Object.hasOwn(agentCapabilitySchemas, name), 'Discover an authorized capability first');
+export const agentCategorySchema = z.enum(['materials', 'sources', 'collection', 'governance', 'sharing', 'projects', 'runtime']);
+const args = z.record(z.string(), z.json()), cursor = z.string().min(1).max(4096);
+export const agentEntryToolSchemas = {
+    knowledge_discover: z.object({ query: z.string().trim().min(1).max(500).optional(), category: agentCategorySchema.optional(), tool: agentCapabilityNameSchema.optional(), after: cursor.optional(), limit: z.number().int().min(1).max(8).default(5) }).strict().refine(v => !v.tool || !v.query && !v.category && !v.after),
+    knowledge_execute: z.object({ tool: agentCapabilityNameSchema, arguments: args.default({}) }).strict(),
+};
+export const agentNextActionSchema = agentGuidanceActionSchema;
+const card = z.object({ name: agentCapabilityNameSchema, category: agentCategorySchema, title: z.string().max(256), description: z.string().max(1000), readOnly: z.boolean(), scopeAlternatives: z.array(z.array(z.string())).max(4) }).strict();
+export const agentEntryDataSchemas = {
+    knowledge_discover: z.object({ mode: z.enum(['HOME', 'SEARCH', 'DETAIL']), categories: z.array(z.object({ id: agentCategorySchema, title: z.string(), count: z.number().int().nonnegative() }).strict()).max(7), items: z.array(card).max(8), detail: z.object({ name: agentCapabilityNameSchema, inputSchema: z.json(), outputSchema: z.json() }).strict().nullable(), nextAfter: cursor.nullable(), nextActions: z.array(agentNextActionSchema).max(16), guidance: z.string().max(1000) }).strict(),
+    knowledge_execute: z.object({ capability: agentCapabilityNameSchema, status: z.enum(['COMPLETED', 'NEEDS_INPUT']), result: z.json().nullable(), missingFields: z.array(z.string().max(256)).max(32), nextActions: z.array(agentNextActionSchema).max(16) }).strict(),
+};
+export function agentEntryEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: agentEntryDataSchemas[tool] }).strict(); }
+// Preserve the original opt-in input schema for already installed v1 clients.
+export const agentGuidedV1ToolSchemas = {
+    knowledge_discover: agentEntryToolSchemas.knowledge_discover.safeExtend({ arguments: args.optional(), task: agentTaskInputSchema.optional() }).refine(v => (!v.arguments || Boolean(v.tool)) && (!v.task || !v.query && !v.category && !v.tool && !v.after && !v.arguments)),
+    knowledge_execute: agentEntryToolSchemas.knowledge_execute,
+};
+export const agentGuidedV1InputJsonSchemas = Object.fromEntries(Object.entries(agentGuidedV1ToolSchemas).map(([n, s]) => [n, z.toJSONSchema(s, { target: 'draft-07' })]));
+export const agentGuidedToolSchemas = {
+    knowledge_discover: agentEntryToolSchemas.knowledge_discover.safeExtend({ arguments: args.optional(), resupplyFields: z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,127}$/)).max(32).optional(), task: agentTaskInputSchema.optional() }).refine(v => (!v.arguments || Boolean(v.tool)) && (!v.resupplyFields || Boolean(v.tool) && v.resupplyFields.every(field => Object.hasOwn(agentCapabilitySchemas[v.tool].shape, field))) && (!v.task || !v.query && !v.category && !v.tool && !v.after && !v.arguments && !v.resupplyFields)),
+    knowledge_execute: agentEntryToolSchemas.knowledge_execute,
+};
+export const agentGuidedDataSchemas = {
+    knowledge_discover: agentEntryDataSchemas.knowledge_discover.omit({ mode: true }).extend({ mode: z.enum(['HOME', 'SEARCH', 'DETAIL', 'TASK']), inputHints: z.array(agentInputHintSchema).max(32), taskPlan: agentTaskPlanSchema.nullable() }).strict(),
+    knowledge_execute: agentEntryDataSchemas.knowledge_execute.extend({ inputHints: z.array(agentInputHintSchema).max(32) }).strict(),
+};
+export function agentGuidedEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: agentGuidedDataSchemas[tool] }).strict(); }
+export const agentGuidedInputJsonSchemas = Object.fromEntries(Object.entries(agentGuidedToolSchemas).map(([n, s]) => [n, z.toJSONSchema(s, { target: 'draft-07' })]));
+export const agentGuidedOutputJsonSchemas = Object.fromEntries(Object.keys(agentGuidedToolSchemas).map(n => [n, { type: 'object', oneOf: [z.toJSONSchema(agentGuidedEnvelopeSchema(n), { target: 'draft-07' }), z.toJSONSchema(agentGuidedFailureSchema, { target: 'draft-07' })] }]));
+export function agentCapabilityEnvelopeSchema(name) {
+    if (Object.hasOwn(bodySearchToolSchemas, name))
+        return bodySearchEnvelopeSchema(name);
+    if (Object.hasOwn(resourceToolSchemas, name))
+        return resourceEnvelopeSchema.safeExtend({ data: resourceDataSchemas[name] });
+    if (Object.hasOwn(tenantWebWorkflowToolSchemas, name))
+        return tenantWebWorkflowEnvelopeSchema(name);
+    return tenantRuntimeEnvelopeSchema(name);
+}
+export const agentEntryInputJsonSchemas = Object.fromEntries(Object.entries(agentEntryToolSchemas).map(([n, s]) => [n, z.toJSONSchema(s, { target: 'draft-07' })]));
+export function agentCapabilityDefinition(name) { return { name, inputSchema: z.toJSONSchema(agentCapabilitySchemas[name], { target: 'draft-07' }), outputSchema: z.toJSONSchema(agentCapabilityEnvelopeSchema(name), { target: 'draft-07' }) }; }
+export const agentEntryOutputJsonSchemas = Object.fromEntries(Object.keys(agentEntryToolSchemas).map(n => [n, { type: 'object', oneOf: [z.toJSONSchema(agentEntryEnvelopeSchema(n), { target: 'draft-07' }), z.toJSONSchema(tenantWebWorkflowErrorSchema, { target: 'draft-07' })] }]));
+export const agentEntryProviderSchema = tenantManagementProviderBaseSchema.extend({ schemaVersion: z.literal(26), collectionMode: z.literal('EXPLICIT_HOST_WITH_OPT_IN_DUE'), tools: z.tuple([z.literal('knowledge_discover'), z.literal('knowledge_execute')]), capabilities: z.tuple([z.literal('AGENT_TASK_DISCOVERY_V1')]) }).strict();

package/dist/internal/serving-contracts/agent-guidance-shapes.js

@@ -0,0 +1,12 @@
+/** Optional presentation extension. No new execution authority or automatic actions. */
+import { z } from 'zod';
+import { stableUriSchema, projectKeySchema } from '../contracts/index.js';
+import { tenantWebWorkflowErrorSchema } from './tenant-web-workflow.js';
+export const agentGuidanceHeader = 'x-knowledge-agent-guidance', agentGuidanceFeature = 'task-guidance-v1', agentResupplyGuidanceFeature = 'task-guidance-v2';
+export const agentGuidanceActionSchema = z.object({ id: z.string().min(1).max(128), title: z.string().min(1).max(256), tool: z.enum(['knowledge_discover', 'knowledge_execute']), arguments: z.record(z.string(), z.json()), canExecute: z.boolean(), automatic: z.literal(false), missingFields: z.array(z.string().max(256)).max(32), reasonCode: z.string().max(128) }).strict();
+export const agentInputHintSchema = z.object({ path: z.string().min(1).max(256), kind: z.enum(['MISSING', 'INVALID', 'UNSUPPORTED', 'CONFLICT']), expected: z.string().max(256), prompt: z.string().max(600), source: z.enum(['USER_INPUT', 'CURRENT_STATE', 'PRIOR_RESULT', 'INDEPENDENT_REVIEW']), choices: z.array(z.json()).max(16), constraints: z.record(z.string(), z.json()) }).strict();
+export const agentTaskContextSchema = z.object({ query: z.string().min(2).max(200).optional(), ref: stableUriSchema.optional(), jobRef: stableUriSchema.optional(), projectRef: stableUriSchema.optional(), projectKey: projectKeySchema.optional(), sourceId: z.string().min(1).max(128).optional(), requestId: z.string().min(1).max(128).optional(), recipientTenantId: z.string().min(1).max(256).optional(), sourceRefs: z.array(stableUriSchema).max(32).optional(), spec: z.record(z.string(), z.json()).optional(), extraction: z.record(z.string(), z.json()).optional(), citation: z.record(z.string(), z.json()).optional() }).strict();
+export const agentTaskInputSchema = z.object({ goal: z.string().trim().min(1).max(1000), context: agentTaskContextSchema.default({}), inputs: z.record(z.string().regex(/^step-[1-6]$/), z.record(z.string(), z.json())).default({}) }).strict();
+export const agentTaskPlanSchema = z.object({ template: z.enum(['RESEARCH_EXISTING', 'COLLECT_WEBSITE', 'INSPECT_COLLECTION', 'VERIFY_CITATION', 'PROJECT_RESEARCH', 'SHARE_MATERIAL', 'GOVERNANCE', 'UNRECOGNIZED']), status: z.literal('SUGGESTED_NOT_EXECUTED'), steps: z.array(z.object({ id: z.string().max(32), title: z.string().max(256), dependsOn: z.array(z.string().max(32)).max(6), capability: z.string().max(128).nullable(), state: z.enum(['READY', 'NEEDS_INPUT', 'NEEDS_PRIOR_RESULT', 'NOT_AUTHORIZED']), action: agentGuidanceActionSchema.nullable(), inputHints: z.array(agentInputHintSchema).max(32) }).strict()).max(6), guidance: z.string().max(1000) }).strict();
+export const agentRecoverySchema = z.object({ reasonCode: z.enum(['INPUT_REQUIRED', 'CURSOR_RESTART_REQUIRED', 'STATE_CHANGED', 'INSPECT_PERSISTED_RESULT', 'SEMANTIC_PLAN_REQUIRED', 'AUTHORITY_REQUIRED', 'ACCESS_BLOCKED', 'OUTCOME_UNKNOWN', 'INSPECT_INPUT']), summary: z.string().max(1000), inputHints: z.array(agentInputHintSchema).max(32), nextActions: z.array(agentGuidanceActionSchema).max(16) }).strict();
+export const agentGuidedFailureSchema = tenantWebWorkflowErrorSchema.extend({ guidance: agentRecoverySchema }).strict();

package/dist/internal/serving-contracts/agent-input-hints.js

@@ -0,0 +1,104 @@
+/** Derive bounded hints from the actual capability schema, never from raw validator messages. */
+import { agentCapabilitySchemas, agentCapabilityDefinition } from './agent-entry.js';
+import { agentInputHintSchema } from './agent-guidance-shapes.js';
+const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+const source = (path, name) => (/decision|reviewedAt/.test(path) || /review/.test(name) && /summary/.test(path)) ? 'INDEPENDENT_REVIEW' : /expected|generation|epoch|revision/i.test(path) ? 'CURRENT_STATE' : /ref|sourceRefs|jobRef|citation/i.test(path) ? 'PRIOR_RESULT' : 'USER_INPUT';
+function prompt(path, origin) {
+    if (origin === 'INDEPENDENT_REVIEW')
+        return '由具备独立审核权限的调用者明确提供结论和依据，不预填 PASS。 Supply an explicit independent review.';
+    if (origin === 'CURRENT_STATE')
+        return '先读取准确目标的当前状态，再提供期望版本；不要猜测或自动重放写入。 Read the current exact target state first.';
+    if (origin === 'PRIOR_RESULT')
+        return '使用前一步实际返回或用户明确给出的准确引用、游标或结果，不构造占位身份。 Use an exact retained result.';
+    if (/requestId/.test(path))
+        return '明确提供本次意图的幂等 requestId；检查已有回执后再决定重试或创建新意图。';
+    if (/contentBase64/.test(path))
+        return '提供真实原始字节的规范 base64，遵守提交大小限制；不在提示中回显内容。';
+    return '补充或修正该字段，遵守准确 schema 的类型、枚举和范围。 Supply or correct this field using the exact schema.';
+}
+function variants(node) { const list = node.anyOf ?? node.oneOf; return [node, ...(Array.isArray(list) ? list : []).map(object)]; }
+function child(node, key) {
+    for (const v of variants(node)) {
+        const next = typeof key === 'number' ? object(v.items) : object(object(v.properties)[key]);
+        if (Object.keys(next).length)
+            return next;
+    }
+    return {};
+}
+function locate(root, path) { let node = root, label = ''; for (const key of path) {
+    if (typeof key === 'symbol')
+        break;
+    const next = child(node, key);
+    if (!Object.keys(next).length)
+        return { node: root, label: 'arguments' };
+    label += typeof key === 'number' ? '[]' : (label ? '.' : '') + key;
+    node = next;
+} return { node, label: label || 'arguments' }; }
+function valueAt(raw, path) { let value = raw; for (const k of path) {
+    if (typeof k === 'symbol' || !value || typeof value !== 'object' || !Object.hasOwn(value, k))
+        return undefined;
+    value = value[String(k)];
+} return value; }
+export function agentInputHints(name, raw) {
+    const parsed = agentCapabilitySchemas[name].safeParse(raw);
+    if (parsed.success)
+        return [];
+    const root = object(agentCapabilityDefinition(name).inputSchema), hints = [], seen = new Set();
+    const add = (node, path, missing, depth = 0) => {
+        if (hints.length >= 32 || seen.has(path) || path.length > 256)
+            return;
+        const required = Array.isArray(node.required) ? node.required.filter((k) => typeof k === 'string') : [];
+        if (missing && required.length && depth < 5) {
+            const before = hints.length;
+            for (const key of required) {
+                const c = child(node, key);
+                if (c.default === undefined)
+                    add(c, path === 'arguments' ? key : path + '.' + key, true, depth + 1);
+            }
+            if (hints.length > before)
+                return;
+        }
+        const origin = source(path, name), choices = variants(node).flatMap(v => Array.isArray(v.enum) ? v.enum : Object.hasOwn(v, 'const') ? [v.const] : []).filter(v => v === null || ['string', 'number', 'boolean'].includes(typeof v)).slice(0, 16);
+        const constraints = Object.fromEntries(['minimum', 'maximum', 'minLength', 'maxLength', 'minItems', 'maxItems', 'pattern'].filter(k => typeof node[k] === 'string' || typeof node[k] === 'number').map(k => [k, node[k]]));
+        seen.add(path);
+        hints.push(agentInputHintSchema.parse({ path, kind: missing ? 'MISSING' : 'INVALID', expected: typeof node.type === 'string' ? node.type : Array.isArray(node.type) ? node.type.join('|') : choices.length ? 'enum' : 'exact schema', prompt: prompt(path, origin), source: origin, choices, constraints }));
+    };
+    for (const issue of parsed.error.issues) {
+        const path = name === 'tenant_web_collect_read' && issue.code === 'custom' && !issue.path.length ? ['stateIndex'] : issue.path;
+        const located = locate(root, path);
+        add(located.node, located.label, valueAt(raw, path) === undefined);
+    }
+    return hints;
+}
+/** Keep only individually valid, declared, small fields in a completion suggestion. Payload bodies are resupplied explicitly. */
+function hasSensitiveField(value, depth = 0) { if (depth > 12)
+    return true; if (!value || typeof value !== 'object')
+    return false; return Object.entries(value).some(([key, item]) => /contentBase64|credential|token|secret|password|authorization/i.test(key) || hasSensitiveField(item, depth + 1)); }
+export function agentResumeArguments(name, raw) {
+    const shape = agentCapabilitySchemas[name].shape, result = {};
+    for (const [key, value] of Object.entries(object(raw))) {
+        if (!shape || !Object.hasOwn(shape, key) || /contentBase64|composition|summary|instruction|credential|token|secret/i.test(key))
+            continue;
+        const parsed = shape[key].safeParse(value);
+        if (parsed.success && parsed.data !== undefined && !hasSensitiveField(parsed.data) && JSON.stringify(parsed.data).length <= 8192)
+            result[key] = parsed.data;
+    }
+    return JSON.parse(JSON.stringify(result));
+}
+/** Explain invalid supplied fields and any payload fields intentionally omitted from suggestions. */
+export function agentCompletionHints(name, raw, resupplyFields = []) {
+    const retained = agentResumeArguments(name, raw), hints = new Map();
+    for (const hint of [...agentInputHints(name, raw), ...agentInputHints(name, retained)])
+        if (!hints.has(hint.path))
+            hints.set(hint.path, hint);
+    const properties = object(object(agentCapabilityDefinition(name).inputSchema).properties);
+    for (const key of new Set([...Object.keys(object(raw)), ...resupplyFields])) {
+        if (!resupplyFields.includes(key) && object(raw)[key] === undefined || !Object.hasOwn(properties, key) || Object.hasOwn(retained, key) || hints.has(key))
+            continue;
+        const node = object(properties[key]), origin = source(key, name);
+        hints.set(key, agentInputHintSchema.parse({ path: key, kind: 'MISSING', expected: typeof node.type === 'string' ? node.type : 'exact schema', prompt: '该字段未进入续作建议；如仍为原意图，请显式重新提供。 ' + prompt(key, origin), source: origin, choices: [], constraints: {} }));
+    }
+    return [...hints.values()].slice(0, 32);
+}
+/** Carry only declared field names, never omitted values, across inspection hops. */
+export function agentResupplyFields(name, raw) { const retained = agentResumeArguments(name, raw), properties = object(object(agentCapabilityDefinition(name).inputSchema).properties); return Object.keys(object(raw)).filter(key => object(raw)[key] !== undefined && Object.hasOwn(properties, key) && !Object.hasOwn(retained, key)).slice(0, 32); }

package/dist/internal/serving-contracts/body-search.js

@@ -0,0 +1,16 @@
+/** Explicit raw-material body search; existing descriptive search contracts stay frozen. */
+import { z } from 'zod';
+import { resourceDirectoryItemSchema, resourceEnvelopeSchema, tenantResourceRefSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+export const agentBodySearchHeader = 'x-knowledge-agent-capabilities';
+export const agentBodySearchFeature = 'body-search-v1';
+const context = { projectRef: stableUriSchema.optional() };
+export const bodyCitationSchema = z.object({ ref: tenantResourceRefSchema, contentHash: sha256Schema, jsonPointer: z.string().max(2048).nullable(), startUtf16: z.number().int().nonnegative().safe(), endUtf16: z.number().int().positive().safe(), quote: z.string().min(1).max(1200) }).strict().refine(v => v.endUtf16 - v.startUtf16 === v.quote.length);
+export const bodySearchToolSchemas = {
+    knowledge_resource_search_body: z.object({ ...context, query: z.string().trim().min(2).max(200), after: z.string().min(1).max(4096).optional(), limit: z.number().int().min(1).max(20).default(5), resourceType: z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/).max(64).optional() }).strict(),
+    knowledge_resource_read_passage: z.object({ ...context, citation: bodyCitationSchema }).strict(),
+};
+export const bodySearchDataSchemas = {
+    knowledge_resource_search_body: z.object({ items: z.array(z.object({ item: resourceDirectoryItemSchema, citation: bodyCitationSchema }).strict()).max(20), nextAfter: z.string().max(4096).nullable(), coverage: z.literal('INDEXED_NATIVE_TEXT_PASSAGES_ONLY'), completeness: z.literal('NOT_ASSESSED'), semantics: z.literal('RAW_MATERIAL_NOT_GOVERNANCE_APPROVAL') }).strict(),
+    knowledge_resource_read_passage: z.object({ citation: bodyCitationSchema, verified: z.literal(true) }).strict(),
+};
+export function bodySearchEnvelopeSchema(name) { return resourceEnvelopeSchema.safeExtend({ data: bodySearchDataSchemas[name] }); }

package/dist/internal/serving-contracts/consumer.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { idSchema, isoDateTimeSchema, richDocumentSchema, schemaVersionSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+import { referenceCorpusSummarySchema, referenceCurrentnessSchema, referenceRecordTypeSchema, referenceSelectorKeySchema, referenceSelectorValueSchema, servingCurrentnessSchema, servingDecisionSchema, servingEvidenceSummarySchema } from './core.js';
+export const consumerProjectRefSchema = stableUriSchema.superRefine((value, ctx) => { try {
+    const u = new URL(value);
+    if (u.protocol !== 'knowledge-project:' || !/^\/tenant\/[^/]+$/.test(u.pathname))
+        ctx.addIssue({ code: 'custom', message: 'projectRef must be a tenant-bound Knowledge project' });
+}
+catch {
+    ctx.addIssue({ code: 'custom', message: 'Invalid projectRef' });
+} });
+export const consumerResourceTypeSchema = z.enum(['artifact', 'evidence', 'reference', 'media']);
+export const consumerSearchInputSchema = z.object({ projectRef: consumerProjectRefSchema, query: z.string().trim().min(1).max(2000), limit: z.number().int().min(1).max(50).optional(), cursor: z.string().min(1).max(4096).optional() }).strict();
+// OAuth 消费者按项目关系发现 Evidence；下一页 ref 只决定位置，不携带授权。
+export const consumerEvidencePageInputSchema = z.object({ projectRef: consumerProjectRefSchema, sourceId: idSchema.optional(), after: stableUriSchema.optional(), limit: z.number().int().min(1).max(50).optional() }).strict();
+export const consumerEvidencePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, decision: servingDecisionSchema, items: z.array(z.object({ decision: servingDecisionSchema, fileDecision: servingDecisionSchema, contentDecision: servingDecisionSchema, evidence: servingEvidenceSummarySchema }).strict()).max(50), nextAfter: stableUriSchema.nullable() }).strict();
+export const consumerReadInputSchema = z.object({ projectRef: consumerProjectRefSchema, ref: stableUriSchema }).strict();
+export const consumerCurrentnessInputSchema = consumerReadInputSchema;
+export const referenceLookupSelectorsSchema = z.record(referenceSelectorKeySchema, z.array(referenceSelectorValueSchema).min(1).max(32)).superRefine((value, ctx) => { const keys = Object.keys(value); if (keys.length > 32)
+    ctx.addIssue({ code: 'custom', message: 'Reference lookup selectors cannot exceed 32 keys' }); for (const key of keys) {
+    const values = value[key] ?? [];
+    if (new Set(values).size !== values.length)
+        ctx.addIssue({ code: 'custom', path: [key], message: 'Reference lookup selector values must be unique' });
+} });
+const referenceLookupFilterObjectSchema = z.object({ jurisdiction: z.string().trim().min(1).max(128).optional(), corpusKeys: z.array(z.string().trim().min(1).max(128)).min(1).max(32).optional(), recordTypes: z.array(referenceRecordTypeSchema).min(1).max(64).optional(), selectors: referenceLookupSelectorsSchema.optional(), effectiveAt: isoDateTimeSchema.optional(), limit: z.number().int().min(1).max(100).optional() }).strict();
+const requireLookupFilter = (value, ctx) => { if (!value.jurisdiction && !value.corpusKeys?.length && !value.recordTypes?.length && !value.selectors && !value.effectiveAt)
+    ctx.addIssue({ code: 'custom', message: 'Reference lookup requires at least one structured filter' }); };
+export const referenceLookupFilterSchema = referenceLookupFilterObjectSchema.superRefine(requireLookupFilter);
+export const consumerReferenceLookupInputSchema = referenceLookupFilterObjectSchema.extend({ projectRef: consumerProjectRefSchema }).superRefine(requireLookupFilter);
+export const consumerSearchItemSchema = z.object({
+    ref: stableUriSchema, resourceType: consumerResourceTypeSchema, title: z.string().max(1000).nullable(), summary: z.string().max(4000).nullable(), contentHash: sha256Schema,
+    sourceRefs: z.array(stableUriSchema).max(256), observedAt: isoDateTimeSchema.nullable(), validUntil: isoDateTimeSchema.nullable(), decision: servingDecisionSchema,
+}).strict();
+export const consumerSearchResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, decision: servingDecisionSchema, searchCoverage: z.enum(['AUTHORIZED_METADATA_V1', 'AUTHORIZED_PRESENTATION_V1']), items: z.array(consumerSearchItemSchema).max(50), nextCursor: z.string().max(4096).nullable() }).strict();
+export const consumerContentDescriptorSchema = z.object({ contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative() }).strict();
+export const consumerReadResponseSchema = z.object({
+    schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, decision: servingDecisionSchema,
+    item: z.object({ ref: stableUriSchema, resourceType: consumerResourceTypeSchema, descriptor: consumerContentDescriptorSchema.nullable(), content: z.string().nullable(), encoding: z.enum(['utf8', 'base64']).nullable(), truncated: z.boolean(), continuation: z.object({ kind: z.literal('AUTHENTICATED_SERVING_CONTENT'), ref: stableUriSchema }).strict().nullable(), presentation: richDocumentSchema.nullable().optional() }).strict().nullable(),
+}).strict();
+export const consumerCurrentnessResponseSchema = z.object({
+    schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, decision: servingDecisionSchema,
+    item: z.object({ ref: stableUriSchema, currentness: z.union([servingCurrentnessSchema, referenceCurrentnessSchema]) }).strict().nullable(),
+}).strict();
+export const consumerReferenceLookupItemSchema = z.object({ decision: servingDecisionSchema, summary: referenceCorpusSummarySchema, payloadDecision: servingDecisionSchema, payload: z.json().nullable() }).strict();
+export const consumerReferenceLookupResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, decision: servingDecisionSchema, lookupCoverage: z.literal('AUTHORIZED_REFERENCE_SELECTORS_V1'), items: z.array(consumerReferenceLookupItemSchema).max(100) }).strict();

package/dist/internal/serving-contracts/core.js

@@ -0,0 +1,76 @@
+// Compatibility exports: immutable Reference facts are owned by contracts.
+import { referenceRecordTypeSchema, referenceSelectorKeySchema, referenceSelectorValueSchema, referenceSelectorsSchema, referenceCurrentnessStateSchema, referenceCurrentnessSchema, referenceCorpusSummarySchema, referenceCorpusRecordSchema } from '../contracts/index.js';
+export { referenceRecordTypeSchema, referenceSelectorKeySchema, referenceSelectorValueSchema, referenceSelectorsSchema, referenceCurrentnessStateSchema, referenceCurrentnessSchema, referenceCorpusSummarySchema, referenceCorpusRecordSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { accessClassificationSchema, artifactKindSchema, artifactStatusSchema, currentnessActionSchema, currentnessStateSchema, idSchema, isoDateTimeSchema, projectKeySchema, schemaVersionSchema, sha256Schema, stableUriSchema, } from '../contracts/index.js';
+export const servingActionSchema = z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']);
+export const servingProblemCodeSchema = z.enum([
+    'NOT_FOUND', 'ACCESS_DENIED', 'CONTENT_ACCESS_DENIED', 'ARTIFACT_NOT_APPROVED', 'ARTIFACT_SUPERSEDED',
+    'SEMANTIC_REVIEW_REQUIRED', 'SEMANTIC_DENIED', 'SEMANTIC_ADMISSION_MISSING',
+    'CURRENTNESS_MISSING', 'CURRENTNESS_REVIEW_REQUIRED', 'CURRENTNESS_DENIED', 'STALE', 'VALIDITY_EXPIRED',
+    'CLAIM_REVIEW_REQUIRED', 'CLAIM_DENIED', 'CLAIM_NOT_EFFECTIVE',
+    'REFERENCE_NOT_COVERED', 'REFERENCE_NOT_EFFECTIVE', 'REFERENCE_VALIDITY_EXPIRED', 'REFERENCE_STALE', 'REFERENCE_UNAVAILABLE', 'REFERENCE_REVIEW_REQUIRED', 'REFERENCE_DENIED',
+    'UNSUPPORTED_RESOURCE', 'GOVERNANCE_NOT_CONFIGURED', 'UNAVAILABLE', 'INTEGRITY_MISMATCH',
+]);
+export const servingDecisionSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    action: servingActionSchema,
+    reasonCodes: z.array(servingProblemCodeSchema).max(32),
+    assessedAt: isoDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    if (value.action === 'ALLOW' && value.reasonCodes.length)
+        ctx.addIssue({ code: 'custom', path: ['reasonCodes'], message: 'ALLOW must not carry problem codes' });
+    if (value.action !== 'ALLOW' && !value.reasonCodes.length)
+        ctx.addIssue({ code: 'custom', path: ['reasonCodes'], message: 'Non-ALLOW decision requires a problem code' });
+});
+export const consumerProfileSchema = z.object({
+    schemaVersion: schemaVersionSchema,
+    consumerKey: projectKeySchema,
+    acceptedArtifactKinds: z.array(artifactKindSchema).max(16),
+    acceptedAccess: z.array(accessClassificationSchema).max(7),
+    contentAccess: z.array(accessClassificationSchema).max(7),
+    acceptedReferenceTypes: z.array(referenceRecordTypeSchema).max(128),
+}).strict().superRefine((value, ctx) => {
+    if (new Set(value.acceptedArtifactKinds).size !== value.acceptedArtifactKinds.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedArtifactKinds'], message: 'acceptedArtifactKinds must be unique' });
+    if (new Set(value.acceptedAccess).size !== value.acceptedAccess.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedAccess'], message: 'acceptedAccess must be unique' });
+    if (new Set(value.contentAccess).size !== value.contentAccess.length)
+        ctx.addIssue({ code: 'custom', path: ['contentAccess'], message: 'contentAccess must be unique' });
+    if (value.contentAccess.some((access) => !value.acceptedAccess.includes(access)))
+        ctx.addIssue({ code: 'custom', path: ['contentAccess'], message: 'contentAccess must be a subset of acceptedAccess' });
+    if (value.contentAccess.some((access) => ['PUBLIC_METADATA', 'ACCESS_CONTROLLED', 'UNKNOWN'].includes(access)))
+        ctx.addIssue({ code: 'custom', path: ['contentAccess'], message: 'Metadata-only, access-controlled and unknown classes cannot grant content access' });
+    if (new Set(value.acceptedReferenceTypes).size !== value.acceptedReferenceTypes.length)
+        ctx.addIssue({ code: 'custom', path: ['acceptedReferenceTypes'], message: 'acceptedReferenceTypes must be unique' });
+});
+export const servingContentDescriptorSchema = z.object({
+    contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative(),
+}).strict();
+export const servingArtifactSummarySchema = z.object({
+    ref: stableUriSchema, identityRef: stableUriSchema, projectKey: projectKeySchema, projectRef: stableUriSchema.nullable().default(null), artifactId: idSchema, kind: artifactKindSchema,
+    version: z.number().int().positive(), status: artifactStatusSchema, access: accessClassificationSchema, title: z.string().max(500).nullable(),
+    createdAt: isoDateTimeSchema, observedAt: isoDateTimeSchema.nullable(), validUntil: isoDateTimeSchema.nullable(), content: servingContentDescriptorSchema,
+}).strict();
+export const servingArtifactDetailSchema = servingArtifactSummarySchema.extend({
+    evidenceRefs: z.array(stableUriSchema).max(256), relatedRefs: z.array(stableUriSchema).max(256), supersedesRef: stableUriSchema.nullable(),
+}).strict();
+export const servingEvidenceSummarySchema = z.object({
+    evidenceRef: stableUriSchema, projectKey: projectKeySchema, sourceId: idSchema, contentHash: sha256Schema, observedAt: isoDateTimeSchema,
+    access: accessClassificationSchema, canonicalUri: stableUriSchema.nullable(), mediaType: z.string().max(256).nullable(), byteLength: z.number().int().nonnegative().nullable(),
+    projectRef: stableUriSchema.nullable().default(null), sourceSetRef: stableUriSchema.nullable(), sourceItemId: idSchema.nullable(), sourceRevisionRef: stableUriSchema.nullable().default(null), collectionBatchRef: stableUriSchema.nullable().default(null), collectionTaskId: idSchema.nullable().default(null),
+}).strict();
+export const servingSourceSummarySchema = z.object({
+    sourceId: idSchema, familyId: idSchema, authority: z.string().min(1).max(512), access: accessClassificationSchema, freshness: z.string().min(1).max(128),
+    declaredState: z.string().min(1).max(128), coverageState: z.string().max(128).nullable(), asOf: isoDateTimeSchema,
+}).strict();
+export const servingProjectIntentSummarySchema = z.object({
+    projectKey: projectKeySchema, projectRef: stableUriSchema, tenantId: idSchema, revisionRef: stableUriSchema, projectName: z.string().trim().min(1).max(256), updatedAt: isoDateTimeSchema,
+}).strict();
+export const servingProjectSourceSummarySchema = z.object({
+    projectKey: projectKeySchema, projectRef: stableUriSchema, projectIntentRef: stableUriSchema.nullable(), sourceId: idSchema, sourceRef: stableUriSchema, sourceRevisionRef: stableUriSchema, targetId: sha256Schema, targetKind: z.enum(['URL', 'FILE', 'EXECUTOR']), locator: stableUriSchema, executorId: idSchema.nullable().default(null), enabled: z.boolean(), access: accessClassificationSchema, refreshMode: z.enum(['MANUAL', 'INTERVAL']), intervalSeconds: z.number().int().min(60).nullable(), updatedAt: isoDateTimeSchema,
+}).strict();
+export const servingGovernanceSourceSummarySchema = servingSourceSummarySchema;
+export const servingCurrentnessSchema = z.object({
+    subjectRef: stableUriSchema, projectRef: stableUriSchema.nullable().default(null), sourceRevisionRef: stableUriSchema.nullable().default(null), state: currentnessStateSchema, action: currentnessActionSchema, assessedAt: isoDateTimeSchema, dueAt: isoDateTimeSchema.nullable(), staleAt: isoDateTimeSchema.nullable(), reasonCode: z.string().min(1).max(128),
+}).strict();

package/dist/internal/serving-contracts/http.js

@@ -0,0 +1,64 @@
+import { rawMaterialDirectoryItemSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { accessClassificationSchema, isoDateTimeSchema, projectKeySchema, richDocumentSchema, schemaVersionSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+import { referenceCorpusRecordSchema, referenceCorpusSummarySchema, servingArtifactDetailSchema, servingArtifactSummarySchema, servingCurrentnessSchema, servingDecisionSchema, servingEvidenceSummarySchema, servingSourceSummarySchema, servingProjectIntentSummarySchema, servingProjectSourceSummarySchema, } from './core.js';
+import { consumerProjectRefSchema, consumerReferenceLookupItemSchema } from './consumer.js';
+const decisionArtifactSummarySchema = z.object({ decision: servingDecisionSchema, artifact: servingArtifactSummarySchema }).strict();
+const decisionEvidenceSummarySchema = z.object({ decision: servingDecisionSchema, evidence: servingEvidenceSummarySchema }).strict();
+const decisionProjectSourceSummarySchema = z.object({ decision: servingDecisionSchema, source: servingProjectSourceSummarySchema }).strict();
+const decisionReferenceSummarySchema = z.object({ decision: servingDecisionSchema, record: referenceCorpusSummarySchema }).strict();
+export const servingApiErrorSchema = z.object({ errorCode: z.string().trim().min(1).max(128).regex(/^[A-Z0-9_]+$/) }).strict();
+export const servingHealthResponseSchema = z.object({ schemaVersion: schemaVersionSchema, status: z.literal('ok'), service: z.literal('knowledge-api'), codeRevision: z.string().trim().min(1).max(128) }).strict();
+export const servingArtifactListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionArtifactSummarySchema).max(1000) }).strict();
+/** Live, authorization-scoped page. A cursor is a position hint, never a grant or snapshot. */
+export const servingArtifactPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionArtifactSummarySchema).max(100), nextAfter: z.string().max(4096).nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED'), versionCoverage: z.literal('AUTHORIZED_REFERENCES_ONLY') }).strict();
+/** Raw immutable snapshots remain separate from governed Knowledge decisions. */
+export const servingArtifactMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('ARTIFACT_SNAPSHOT'), items: z.array(z.object({ decision: servingDecisionSchema, governanceDecision: servingDecisionSchema, artifact: servingArtifactSummarySchema }).strict()).max(100), nextAfter: z.string().max(4096).nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED'), versionCoverage: z.literal('AUTHORIZED_REFERENCES_ONLY') }).strict();
+export const servingArtifactMaterialResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('ARTIFACT_SNAPSHOT'), decision: servingDecisionSchema, governanceDecision: servingDecisionSchema, artifact: servingArtifactDetailSchema.nullable() }).strict();
+export const servingArtifactResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, artifact: servingArtifactDetailSchema.nullable() }).strict();
+export const servingEvidenceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionEvidenceSummarySchema).max(1000) }).strict();
+// 不把文件可下载误称为结构化正文；状态不包含任何未授权的正文派生文本。
+export const servingEvidenceFormatQualitySchema = z.object({ format: z.enum(['HTML', 'PDF', 'FEED', 'XML', 'MARKDOWN', 'CSV', 'JSON', 'IMAGE', 'VIDEO', 'AUDIO', 'TEXT', 'OTHER']), rawFile: z.enum(['AVAILABLE', 'DENIED']), projection: z.enum(['READY', 'EMPTY', 'MISSING', 'UNSUPPORTED', 'DENIED']), media: z.enum(['COMPLETE', 'PARTIAL', 'NONE', 'UNASSESSED']) }).strict();
+// 通用文件发现页区分原始文件读取权和已审核知识的正文消费权。
+export const servingEvidencePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionEvidenceSummarySchema.extend({ fileDecision: servingDecisionSchema, contentDecision: servingDecisionSchema, formatQuality: servingEvidenceFormatQualitySchema.optional(), presentation: z.object({ title: z.string().max(1000).nullable(), summary: z.string().max(4000).nullable(), byline: z.string().max(1000).nullable(), publishedAt: isoDateTimeSchema.nullable(), language: z.string().max(64).nullable(), topics: z.array(z.string().max(160)).max(32).optional(), documentRef: stableUriSchema, documentContentHash: sha256Schema, quality: z.object({ bodyCharacters: z.number().int().nonnegative(), mediaTotal: z.number().int().nonnegative(), mediaMirrored: z.number().int().nonnegative(), mediaUnavailable: z.number().int().nonnegative(), mediaTooLarge: z.number().int().nonnegative() }).strict() }).strict().nullable().optional() })).max(100), nextAfter: stableUriSchema.nullable() }).strict().superRefine((value, ctx) => { for (let index = 0; index < value.items.length; index++) {
+    const item = value.items[index];
+    if (item.presentation && item.fileDecision.action !== 'ALLOW')
+        ctx.addIssue({ code: 'custom', path: ['items', index, 'presentation'], message: 'Body-derived presentation requires raw-file authorization' });
+} });
+/** A readable representation of original Evidence, never a reviewed Knowledge artifact. */
+export const servingEvidencePresentationResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, contentClass: z.literal('RAW_EVIDENCE_PRESENTATION'), presentation: z.object({ sourceEvidenceRef: stableUriSchema, sourceContentHash: sha256Schema, documentRef: stableUriSchema, documentContentHash: sha256Schema, document: richDocumentSchema }).strict().nullable() }).strict().superRefine((value, ctx) => {
+    if ((value.decision.action === 'ALLOW') !== Boolean(value.presentation))
+        ctx.addIssue({ code: 'custom', path: ['presentation'], message: 'Presentation must match the current decision' });
+    if (value.presentation && (value.presentation.document.role !== 'SOURCE_MIRROR' || value.presentation.document.sourceContentHash !== value.presentation.sourceContentHash || value.presentation.document.primarySourceEvidenceRef !== value.presentation.sourceEvidenceRef || value.presentation.document.projectKey !== /^evidence:\/\/([^/]+)\//.exec(value.presentation.sourceEvidenceRef)?.[1]))
+        ctx.addIssue({ code: 'custom', path: ['presentation'], message: 'Presentation source identity mismatch' });
+});
+export const oauthMaterialPresentationResponseSchema = servingEvidencePresentationResponseSchema.safeExtend({ projectRef: consumerProjectRefSchema });
+export const servingEvidenceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, evidence: servingEvidenceSummarySchema.nullable() }).strict();
+export const servingProjectIntentResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, project: servingProjectIntentSummarySchema.nullable() }).strict();
+export const servingProjectSourceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionProjectSourceSummarySchema).max(1000) }).strict();
+export const servingProjectSourceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, source: servingProjectSourceSummarySchema.nullable() }).strict();
+export const servingSourceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, source: servingSourceSummarySchema.nullable() }).strict();
+export const servingCurrentnessResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, currentness: servingCurrentnessSchema.nullable() }).strict();
+export const servingReferenceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionReferenceSummarySchema).max(1000) }).strict();
+export const servingReferenceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, record: referenceCorpusRecordSchema.nullable() }).strict();
+export const servingReferenceMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('REFERENCE_SNAPSHOT'), items: z.array(z.object({ decision: servingDecisionSchema, record: referenceCorpusSummarySchema }).strict()).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const servingReferenceMaterialResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('REFERENCE_SNAPSHOT'), decision: servingDecisionSchema, record: referenceCorpusRecordSchema.nullable() }).strict();
+/** Type-neutral discovery over current project references; kind is descriptive, never an admission list. */
+export const servingMaterialDirectoryItemSchema = rawMaterialDirectoryItemSchema;
+export const servingMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED') }).strict();
+export const servingMaterialRoutePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, routeId: z.string().regex(/^[a-f0-9]{64}$/), contentClass: z.literal('MATERIAL_DIRECTORY'), routeState: z.enum(['ACTIVE', 'REVOKED', 'UNBOUND']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const materialRoutePartitionSchema = z.object({ routeId: z.string().regex(/^[a-f0-9]{64}$/), sourceProjectKey: projectKeySchema, matchType: z.enum(['SOURCE_PROJECT', 'SOURCE_SET', 'REF']), matchValue: z.string().min(1).max(4096) }).strict();
+export const servingMaterialPartitionsResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, coverage: z.literal('OWNER_LEGACY_AND_ACTIVE_ROUTES'), items: z.array(materialRoutePartitionSchema).max(100), nextAfterRouteId: z.string().regex(/^[a-f0-9]{64}$/).nullable() }).strict();
+export const servingMaterialPartitionPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), partition: z.enum(['OWNER', 'LEGACY']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const servingMaterialSearchResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, queryCoverage: z.literal('DESCRIPTIVE_METADATA_V1'), order: z.literal('INDEX_ROWID_ASC'), indexState: z.enum(['PARTIAL_BACKFILL', 'SYNCED_AS_OF_LAST_OBSERVATION']), configuredSourceCount: z.number().int().nonnegative(), items: z.array(z.object({ item: servingMaterialDirectoryItemSchema, title: z.string().max(512), summary: z.string().max(1024) }).strict()).max(20), nextAfterId: z.number().int().positive().nullable() }).strict();
+export const oauthMaterialPageResponseSchema = z.discriminatedUnion('resourceType', [
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('all'), contentClass: z.literal('MATERIAL_DIRECTORY'), items: servingMaterialPageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('artifact'), contentClass: z.literal('ARTIFACT_SNAPSHOT'), items: servingArtifactMaterialPageResponseSchema.shape.items, nextAfter: z.string().max(4096).nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('evidence'), contentClass: z.literal('RAW_EVIDENCE'), items: servingEvidencePageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('reference'), contentClass: z.literal('REFERENCE_SNAPSHOT'), items: servingReferenceMaterialPageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+]);
+export const servingReferenceLookupResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, lookupCoverage: z.literal('AUTHORIZED_REFERENCE_SELECTORS_V1'), items: z.array(consumerReferenceLookupItemSchema).max(100) }).strict();
+export const servingContentDecisionResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, content: z.null() }).strict();
+export const servingContentHeadersSchema = z.object({ contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative(), assessedAt: z.string().datetime({ offset: true }) }).strict();
+/** Recovery checkpoint is captured before bootstrap; incremental replay starts after headSeq. */
+export const materialOutboxWindowSchema = z.object({ schemaVersion: schemaVersionSchema, tenantId: z.string().min(1), retainedThroughSeq: z.number().int().nonnegative().safe(), headSeq: z.number().int().nonnegative().safe() }).strict().refine(value => value.retainedThroughSeq <= value.headSeq, { message: 'Outbox floor must not exceed head' });

package/dist/{types → internal}/serving-contracts/index.d.ts

@@ -16,6 +16,7 @@ export * from './tenant-web-crawl.js';
 export * from './tenant-web-dynamic.js';
 export * from './tenant-web-content.js';
 export * from './tenant-web-workflow.js';
+export * from './tenant-session.js';
 export * from './agent-entry.js';
 export * from './agent-catalog.js';
 export * from './body-search.js';

package/dist/internal/serving-contracts/index.js

@@ -0,0 +1,25 @@
+export * from './core.js';
+export * from './http.js';
+export * from './consumer.js';
+export * from './mcp.js';
+export * from './management.js';
+export * from './material-capabilities.js';
+export * from './material-index-status.js';
+// CLI、MCP 与 HTTPS 共享同一 Agent 治理合同，避免各入口自行解释状态。
+export * from './workflow.js';
+export * from './tenant-governance.js';
+export * from './tenant-management.js';
+export * from './tenant-workspace.js';
+export * from './tenant-project.js';
+export * from './tenant-runtime.js';
+export * from './tenant-web.js';
+export * from './tenant-web-crawl.js';
+export * from './tenant-web-dynamic.js';
+export * from './tenant-web-content.js';
+export * from './tenant-web-workflow.js';
+export * from './tenant-session.js';
+export * from './agent-entry.js';
+export * from './agent-catalog.js';
+export * from './body-search.js';
+export * from './agent-guidance-shapes.js';
+export * from './agent-input-hints.js';

package/dist/internal/serving-contracts/management.js

@@ -0,0 +1,15 @@
+/** 管理 MCP 的参数只携带项目引用和治理输入；项目 Key、Tenant 和节点均由服务端绑定解析。 */
+import { z } from 'zod';
+import { artifactIdSchema, isoDateTimeSchema, publicationProfileSchema, richCompositionDraftSchema, stableUriSchema } from '../contracts/index.js';
+import { consumerProjectRefSchema } from './consumer.js';
+const version = z.number().int().nonnegative();
+const base = z.object({ projectRef: consumerProjectRefSchema }).strict();
+export const managementComposeInputSchema = base.extend({ sourceEvidenceRefs: z.array(stableUriSchema).min(1).max(64), primarySourceEvidenceRef: stableUriSchema.optional(), artifactId: artifactIdSchema, expectedVersion: version, composedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema.optional(), outputKind: z.enum(['KNOWLEDGE', 'INSIGHT']), publicationProfile: publicationProfileSchema.optional(), title: z.string().trim().min(1).max(1000).optional(), composition: richCompositionDraftSchema.optional() }).strict();
+export const managementSubmitInputSchema = base.extend({ ref: stableUriSchema, expectedVersion: version, createdAt: isoDateTimeSchema }).strict();
+export const managementReviewInputSchema = base.extend({ targetRef: stableUriSchema, expectedVersion: version, decision: z.enum(['PASS', 'REWORK', 'REJECT']), reviewedAt: isoDateTimeSchema, summary: z.string().trim().min(1).max(8000), evidenceRefs: z.array(stableUriSchema).max(64).optional() }).strict();
+export const managementFinalizeInputSchema = base.extend({ ref: stableUriSchema, expectedVersion: version, nextStatus: z.enum(['APPROVED', 'REWORK_REQUIRED', 'REJECTED']), reviewRef: stableUriSchema, createdAt: isoDateTimeSchema }).strict();
+export const managementResultSchema = z.object({ schemaVersion: z.literal(1), projectRef: consumerProjectRefSchema, ref: stableUriSchema, kind: z.enum(['KNOWLEDGE', 'INSIGHT', 'REVIEW']), version: z.number().int().positive(), status: z.enum(['DRAFT', 'READY_FOR_REVIEW', 'APPROVED', 'REWORK_REQUIRED', 'REJECTED']), contentHash: z.string().regex(/^sha256:[a-f0-9]{64}$/), inserted: z.boolean() }).strict();
+// MCP 公告和服务端参数校验从同一组合同生成，避免工具描述与实际输入漂移。
+export const managementToolInputSchemas = { knowledge_compose: z.toJSONSchema(managementComposeInputSchema, { target: 'draft-07' }), knowledge_submit_review: z.toJSONSchema(managementSubmitInputSchema, { target: 'draft-07' }), knowledge_review: z.toJSONSchema(managementReviewInputSchema, { target: 'draft-07' }), knowledge_finalize_review: z.toJSONSchema(managementFinalizeInputSchema, { target: 'draft-07' }) };
+export const managementToolErrorOutputSchema = { type: 'object', properties: { errorCode: { type: 'string' }, completedPhase: { type: 'string', enum: ['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED'] }, ref: z.toJSONSchema(stableUriSchema, { target: 'draft-07' }) }, required: ['errorCode'], additionalProperties: false };
+export const managementToolOutputSchema = { type: 'object', oneOf: [z.toJSONSchema(managementResultSchema, { target: 'draft-07' }), managementToolErrorOutputSchema] };

package/dist/internal/serving-contracts/material-capabilities.js

@@ -0,0 +1,14 @@
+import { rawRetrievalDecisionSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { projectKeySchema, stableUriSchema, sha256Schema } from '../contracts/index.js';
+import { servingMaterialDirectoryItemSchema } from './http.js';
+import { materialReadStateSchema, materialCapabilitySchema } from '../contracts/index.js';
+export { materialReadStateSchema, materialCapabilitySchema } from '../contracts/index.js';
+export const materialCapabilityResponseSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, material: materialCapabilitySchema }).strict();
+export const materialCapabilityPageSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, items: z.array(materialCapabilitySchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const materialMediaCapabilityPageSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, ref: stableUriSchema, sourceContentHash: sha256Schema, documentRef: stableUriSchema.nullable(), documentContentHash: sha256Schema.nullable(), state: z.enum(['READY', 'MISSING', 'DENIED', 'UNSUPPORTED', 'INTEGRITY_MISMATCH']), items: z.array(z.object({ ordinal: z.number().int().nonnegative(), kind: z.enum(['IMAGE', 'VIDEO', 'AUDIO']), sourceUrl: z.string().url(), canonicalUrl: z.string().url().nullable(), availability: z.enum(['MIRRORED', 'REMOTE_ONLY', 'UNAVAILABLE']), mediaRef: stableUriSchema.nullable(), contentHash: sha256Schema.nullable(), mediaType: z.string().nullable(), byteLength: z.number().int().nonnegative().safe().nullable(), state: z.enum(['READY', 'REMOTE_ONLY', 'UNAVAILABLE', 'MISSING', 'DENIED', 'INTEGRITY_MISMATCH']), representation: materialCapabilitySchema.shape.representation.nullable() }).strict()).max(100), nextAfterOrdinal: z.number().int().nonnegative().nullable() }).strict();
+export const oauthMaterialCapabilityResponseSchema = materialCapabilityResponseSchema.extend({ projectRef: stableUriSchema }).strict();
+export const oauthMaterialCapabilityPageSchema = materialCapabilityPageSchema.extend({ projectRef: stableUriSchema }).strict();
+export const oauthMaterialMediaCapabilityPageSchema = materialMediaCapabilityPageSchema.extend({ projectRef: stableUriSchema }).strict();
+/** Authenticated API-key discovery uses service-relative paths and never substitutes OAuth authority. */
+export const apiKeyMaterialContractSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, authentication: z.literal('API_KEY'), resourceTypeMode: z.literal('OPEN_IDENTIFIER'), capabilitiesEndpoint: z.literal('/v3/material-capabilities'), capabilityPageEndpoint: z.literal('/v3/material-page'), fileEndpoint: z.literal('/v2/material-file'), mediaPageEndpoint: z.literal('/v3/material-media-page'), indexStatusEndpoint: z.literal('/v3/material-index-status'), fileMethods: z.tuple([z.literal('GET'), z.literal('HEAD')]), fileRange: z.literal('SINGLE') }).strict();

package/dist/internal/serving-contracts/material-index-status.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import { projectKeySchema, idSchema, stableUriSchema } from '../contracts/index.js';
+export const materialIndexPositionSchema = z.object({ sourceProjectKey: projectKeySchema, nodeId: idSchema }).strict();
+export const materialIndexStatusSchema = z.object({ schemaVersion: z.literal(2), projectKey: projectKeySchema, queryCoverage: z.literal('DESCRIPTIVE_METADATA_V1'), indexedFields: z.tuple([z.literal('TITLE'), z.literal('SUMMARY')]), bodyIndexed: z.literal(false), semanticIndexed: z.literal(false), items: z.array(materialIndexPositionSchema.extend({ directoryThroughSeq: z.number().int().nonnegative().safe(), searchThroughSeq: z.number().int().nonnegative().safe().nullable(), observedMaxSeq: z.number().int().nonnegative().safe().nullable(), checkpointUpdatedAt: z.string().datetime({ offset: true }).nullable(), state: z.enum(['PARTIAL_BACKFILL', 'SYNCED_AS_OF_CHECKPOINT']) }).strict()).max(100), nextAfter: materialIndexPositionSchema.nullable() }).strict();
+export const oauthMaterialIndexStatusSchema = materialIndexStatusSchema.extend({ projectRef: stableUriSchema }).strict();