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

package/dist/internal/serving-contracts/tenant-web-workflow.js

@@ -0,0 +1,36 @@
+/** Explicit Provider25 operations; earlier registries remain frozen. */
+import { z } from 'zod';
+import { tenantWebWorkflowStatusSchema, tenantWebScheduleSchema, tenantWebControlInputSchema, tenantWebLifecycleReceiptSchema, tenantWebWorkflowJobSchema, tenantWebContentOutcomeSchema, tenantWebJobRefSchema, tenantCollectionCycleSchema, tenantResourceRefSchema, sha256Schema, isoDateTimeSchema, materialTenantIdSchema, tenantStorageKey, resourceDataSchemas } from '../contracts/index.js';
+import { tenantWebContentToolSchemas, tenantWebContentDataSchemas, tenantWebContentWorkspaceToolSchemas, tenantWebContentProviderSchema, tenantWebContentErrorSchema } from './tenant-web-content.js';
+import { tenantWebScopesForInput } from './tenant-web.js';
+import { tenantRuntimeEnvelopeSchema } from './tenant-runtime.js';
+const count = z.number().int().nonnegative().safe(), cursor = z.string().min(1).max(4096), job = z.object({ jobRef: tenantWebJobRefSchema }).strict(), page = job.extend({ after: cursor.optional(), limit: z.number().int().min(1).max(100).default(20) }), schedule = tenantWebScheduleSchema.default({ mode: 'ONCE' }), observation = z.object({ ref: tenantResourceRefSchema, contentHash: sha256Schema, sourceUrl: z.string().url(), observedAt: isoDateTimeSchema }).strict().nullable();
+export const tenantWebWorkflowToolSchemas = {
+    tenant_web_collect_preview: tenantWebContentToolSchemas.tenant_web_collect_preview.extend({ schedule }),
+    tenant_web_collect_submit: tenantWebContentToolSchemas.tenant_web_collect_submit.extend({ schedule }),
+    tenant_web_collect_status: job, tenant_web_collect_results: page, tenant_web_collect_cycles: page,
+    tenant_web_collect_control: tenantWebControlInputSchema,
+    tenant_web_collect_refresh: job.extend({ requestId: tenantCollectionCycleSchema, expectedEpoch: count }),
+    tenant_web_collect_read: job.extend({ kind: z.enum(['ORIGINAL', 'DOM', 'RESULT']), index: count.max(21999), stateIndex: count.max(100).optional() }).refine(v => v.kind === 'DOM' ? v.stateIndex !== undefined : v.stateIndex === undefined),
+    tenant_web_collect_index_status: z.object({}).strict(),
+};
+export const tenantWebWorkflowWorkspaceToolSchemas = { ...tenantWebContentWorkspaceToolSchemas, ...tenantWebWorkflowToolSchemas };
+export function tenantWebWorkflowScopesForInput(name, raw) { if (!Object.hasOwn(tenantWebWorkflowToolSchemas, name))
+    return tenantWebScopesForInput(name, raw); tenantWebWorkflowToolSchemas[name].parse(raw); return name === 'tenant_web_collect_read' || name === 'tenant_web_collect_index_status' ? ['knowledge.collect', 'knowledge.material.read'] : ['tenant_web_collect_status', 'tenant_web_collect_results', 'tenant_web_collect_cycles'].includes(name) ? ['knowledge.collect'] : ['knowledge.collect', 'knowledge.source.manage']; }
+export const tenantWebWorkflowDataSchemas = {
+    tenant_web_collect_preview: tenantWebContentDataSchemas.tenant_web_collect_preview.safeExtend({ schedule: tenantWebScheduleSchema }),
+    tenant_web_collect_submit: z.object({ inserted: z.boolean(), job: tenantWebWorkflowStatusSchema }).strict(),
+    tenant_web_collect_status: tenantWebWorkflowStatusSchema,
+    tenant_web_collect_results: job.extend({ items: z.array(tenantWebContentOutcomeSchema.safeExtend({ original: observation, observation })).max(100), through: count, nextAfter: cursor.nullable(), available: count, terminal: z.boolean() }),
+    tenant_web_collect_cycles: job.extend({ rootJobRef: tenantWebJobRefSchema, items: z.array(z.object({ jobRef: tenantWebJobRefSchema, cycle: tenantWebWorkflowJobSchema.shape.cycle, submittedAt: isoDateTimeSchema }).strict()).max(100), through: count, nextAfter: cursor.nullable() }),
+    tenant_web_collect_control: z.object({ replayed: z.boolean(), receipt: tenantWebLifecycleReceiptSchema, job: tenantWebWorkflowStatusSchema }).strict(),
+    tenant_web_collect_refresh: z.object({ inserted: z.boolean(), job: tenantWebWorkflowStatusSchema }).strict(),
+    tenant_web_collect_read: job.extend({ ref: tenantResourceRefSchema, result: resourceDataSchemas.knowledge_resource_read }),
+    tenant_web_collect_index_status: resourceDataSchemas.knowledge_resource_index_status,
+};
+export const tenantWebWorkflowErrorSchema = tenantWebContentErrorSchema.extend({ completedPhase: z.enum([...tenantWebContentErrorSchema.shape.completedPhase.unwrap().options, 'WEB_CONTROL_COMMITTED']).optional(), errorCode: z.enum([...tenantWebContentErrorSchema.shape.errorCode.options, 'TENANT_WEB_CONTROL_CONFLICT', 'TENANT_WEB_CANCELLED', 'TENANT_WEB_PAUSED', 'TENANT_WEB_CYCLE_PENDING', 'TENANT_WEB_RUNTIME_OR_DELEGATION_UNAVAILABLE']) }).strict();
+export function tenantWebWorkflowEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantWebWorkflowDataSchemas[tool] }).strict().superRefine((v, c) => { const d = v.data, key = tenantStorageKey(v.tenantId); if ([d.jobRef, d.rootJobRef, d.job?.jobRef, ...(d.items ?? []).map(i => i.jobRef)].some(ref => ref && !ref.startsWith('tenant-web-collection://' + key + '/')) || [d.ref, ...(d.items ?? []).flatMap(i => [i.documentRef, i.original?.ref, i.observation?.ref])].some(ref => ref && !ref.startsWith('tenant-resource://' + key + '/')) || d.result?.item && (d.result.item.ownerTenantId !== v.tenantId || d.result.item.ref !== d.ref))
+    c.addIssue({ code: 'custom', message: 'Exact Tenant workflow/result identity required' }); }); }
+export const tenantWebWorkflowInputJsonSchemas = Object.fromEntries(Object.entries(tenantWebWorkflowWorkspaceToolSchemas).map(([n, s]) => [n, z.toJSONSchema(s, { target: 'draft-07' })]));
+export const tenantWebWorkflowOutputJsonSchemas = Object.fromEntries(Object.keys(tenantWebWorkflowWorkspaceToolSchemas).map(n => [n, { type: 'object', oneOf: [z.toJSONSchema(Object.hasOwn(tenantWebWorkflowToolSchemas, n) ? tenantWebWorkflowEnvelopeSchema(n) : tenantRuntimeEnvelopeSchema(n), { target: 'draft-07' }), z.toJSONSchema(tenantWebWorkflowErrorSchema, { target: 'draft-07' })] }]));
+export const tenantWebWorkflowProviderSchema = z.object({ ...tenantWebContentProviderSchema.shape, schemaVersion: z.literal(25), collectionMode: z.literal('EXPLICIT_HOST_WITH_OPT_IN_DUE'), tools: z.array(z.string()).length(Object.keys(tenantWebWorkflowWorkspaceToolSchemas).length), capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1'), z.literal('TENANT_WORKSPACE_METADATA_V1'), z.literal('TENANT_PROJECT_CONTEXT_V1'), z.literal('TENANT_RUNTIME_STATUS_V1'), z.literal('TENANT_WEB_COLLECTION_SPEC_V1'), z.literal('TENANT_WEB_CRAWL_V1'), z.literal('TENANT_WEB_DYNAMIC_V1'), z.literal('TENANT_WEB_CONTENT_V1'), z.literal('TENANT_WEB_WORKFLOW_V1')]) }).strict().refine(v => new Set(v.tools).size === Object.keys(tenantWebWorkflowWorkspaceToolSchemas).length && v.tools.every(t => Object.hasOwn(tenantWebWorkflowWorkspaceToolSchemas, t)));

package/dist/internal/serving-contracts/tenant-web.js

@@ -0,0 +1,53 @@
+/** Provider21 增量能力；17–20 的注册表、默认版本和既有错误合同保持。 */
+import { z } from 'zod';
+import { tenantWebSpecSchema, tenantWebSummarySchema, tenantWebJobRefSchema, tenantWebSpecRevision, tenantCollectionCycleSchema, materialTenantIdSchema, tenantStorageKey, TENANT_WEB_SPEC_CAPABILITY } from '../contracts/index.js';
+import { tenantRuntimeWorkspaceToolSchemas, tenantRuntimeWorkspaceDataSchemas, tenantRuntimeEnvelopeSchema, tenantRuntimeProviderSchema, tenantRuntimeScopesForInput, tenantRuntimeAuthorization } from './tenant-runtime.js';
+import { tenantProjectErrorSchema } from './tenant-project.js';
+import { tenantManagementSafeErrorRef } from './tenant-management.js';
+export const tenantWebToolSchemas = {
+    tenant_web_collect_preview: z.object({ spec: tenantWebSpecSchema }).strict(),
+    tenant_web_collect_submit: z.object({ requestId: tenantCollectionCycleSchema, spec: tenantWebSpecSchema }).strict(),
+    tenant_web_collect_status: z.object({ jobRef: tenantWebJobRefSchema }).strict(),
+};
+export const tenantWebDataSchemas = {
+    tenant_web_collect_preview: z.object({ spec: tenantWebSpecSchema, specRevision: tenantWebSummarySchema.shape.specRevision, networkValidated: z.literal(false), budgetReserved: z.literal(false), execution: z.literal('UNAVAILABLE'), reason: z.literal('S2_NOT_IMPLEMENTED'), requirementsState: z.literal('DECLARED_NOT_EVALUATED') }).strict().superRefine((v, ctx) => { if (v.specRevision !== tenantWebSpecRevision(v.spec))
+        ctx.addIssue({ code: 'custom', message: 'Preview specification identity mismatch' }); }),
+    tenant_web_collect_submit: z.object({ inserted: z.boolean(), job: tenantWebSummarySchema }).strict(),
+    tenant_web_collect_status: tenantWebSummarySchema,
+};
+export const tenantWebWorkspaceToolSchemas = { ...tenantRuntimeWorkspaceToolSchemas, ...tenantWebToolSchemas };
+export const tenantWebWorkspaceDataSchemas = { ...tenantRuntimeWorkspaceDataSchemas, ...tenantWebDataSchemas };
+export const tenantWebErrorSchema = tenantProjectErrorSchema.extend({ completedPhase: z.enum([...tenantProjectErrorSchema.shape.completedPhase.unwrap().options, 'WEB_INTENT_PERSISTED']).optional() }).strict();
+export function tenantWebSafeErrorRef(raw, tenantId) {
+    if (typeof raw === 'string' && new RegExp('^tenant-web-collection://' + tenantStorageKey(tenantId) + '/[a-f0-9]{64}$').test(raw))
+        return raw;
+    return tenantManagementSafeErrorRef(raw, tenantId);
+}
+export function tenantWebScopesForInput(name, raw) {
+    if (Object.hasOwn(tenantWebToolSchemas, name)) {
+        tenantWebToolSchemas[name].parse(raw);
+        return name === 'tenant_web_collect_status' ? ['knowledge.collect'] : ['knowledge.source.manage', 'knowledge.collect'];
+    }
+    return tenantRuntimeScopesForInput(name, raw);
+}
+export function tenantWebAuthorization(name) {
+    if (Object.hasOwn(tenantWebToolSchemas, name))
+        return { selection: 'FIXED', scopeAlternatives: [name === 'tenant_web_collect_status' ? ['knowledge.collect'] : ['knowledge.source.manage', 'knowledge.collect']] };
+    return tenantRuntimeAuthorization(name);
+}
+export function tenantWebEnvelopeSchema(tool) {
+    return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantWebDataSchemas[tool] }).strict().superRefine((value, ctx) => {
+        const envelope = value, ref = envelope.data.jobRef ?? envelope.data.job?.jobRef;
+        if (ref && !ref.startsWith('tenant-web-collection://' + tenantStorageKey(envelope.tenantId) + '/'))
+            ctx.addIssue({ code: 'custom', message: 'Web intent must belong to the exact authenticated Tenant' });
+    });
+}
+export const tenantWebInputJsonSchemas = Object.fromEntries(Object.entries(tenantWebWorkspaceToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const tenantWebOutputJsonSchemas = Object.fromEntries(Object.keys(tenantWebWorkspaceToolSchemas).map(name => [name, { type: 'object', oneOf: [z.toJSONSchema(Object.hasOwn(tenantWebToolSchemas, name) ? tenantWebEnvelopeSchema(name) : tenantRuntimeEnvelopeSchema(name), { target: 'draft-07' }), z.toJSONSchema(tenantWebErrorSchema, { target: 'draft-07' })] }]));
+export const tenantWebProviderSchema = z.object({ ...tenantRuntimeProviderSchema.shape,
+    schemaVersion: z.literal(21), tools: z.array(z.string()).length(Object.keys(tenantWebWorkspaceToolSchemas).length),
+    capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1'), z.literal('TENANT_WORKSPACE_METADATA_V1'), z.literal('TENANT_PROJECT_CONTEXT_V1'), z.literal('TENANT_RUNTIME_STATUS_V1'), z.literal(TENANT_WEB_SPEC_CAPABILITY)]),
+}).strict().superRefine((value, ctx) => {
+    if (new Set(value.tools).size !== Object.keys(tenantWebWorkspaceToolSchemas).length || value.tools.some(name => !Object.hasOwn(tenantWebWorkspaceToolSchemas, name)))
+        ctx.addIssue({ code: 'custom', message: 'Provider21 tools must match the exact versioned registry' });
+});

package/dist/internal/serving-contracts/tenant-workspace.js

@@ -0,0 +1,28 @@
+/** Provider18 adds explicit metadata reads; Provider17 remains the exact original twenty tools. */
+import { z } from 'zod';
+import { tenantResourceRefSchema, tenantSourceIdSchema, collectionRefreshSchema, stableUriSchema, isoDateTimeSchema, materialTenantIdSchema } from '../contracts/index.js';
+import { tenantManagementToolSchemas, tenantManagementDataSchemas, tenantManagementScopesForInput, tenantManagementAuthorization, tenantManagementProviderBaseSchema, tenantManagementErrorSchema } from './tenant-management.js';
+const page = { after: z.string().min(1).max(4096).optional(), limit: z.number().int().min(1).max(100).optional() };
+export const tenantWorkStageSchema = z.enum(['ALL', 'RESEARCH', 'DRAFT', 'READY_FOR_REVIEW', 'REWORK_REQUIRED', 'APPROVED']);
+export const tenantWorkspaceExtraToolSchemas = { tenant_source_inventory: z.object(page).strict(), tenant_work_queue: z.object({ ...page, stage: tenantWorkStageSchema.default('ALL') }).strict() };
+const source = z.object({ sourceId: tenantSourceIdSchema, title: z.string().min(1).max(512).nullable(), revisionRef: stableUriSchema.nullable(), generation: z.number().int().positive().safe().nullable(), paused: z.boolean().nullable(), tenantEnabled: z.boolean().nullable(), refresh: collectionRefreshSchema.nullable(), canonicalState: z.enum(['READY', 'UNAVAILABLE', 'INTEGRITY_MISMATCH']) }).strict();
+const artifact = z.object({ ref: tenantResourceRefSchema, title: z.string().max(512), kind: z.string().max(128).nullable(), status: z.string().max(128).nullable(), version: z.number().int().positive().safe().nullable(), recordedAt: isoDateTimeSchema.nullable(), availability: z.enum(['READY', 'UNAVAILABLE', 'INTEGRITY_MISMATCH']), succession: z.enum(['SUCCESSOR_VISIBLE', 'NO_VISIBLE_SUCCESSOR', 'UNCONFIRMED']) }).strict();
+export const tenantWorkspaceExtraDataSchemas = {
+    tenant_source_inventory: z.object({ items: z.array(source).max(100), nextAfter: z.string().max(4096).nullable(), coverage: z.literal('REGISTERED_TENANT_SOURCES') }).strict(),
+    tenant_work_queue: z.object({ items: z.array(artifact).max(100), nextAfter: z.string().max(4096).nullable(), stage: tenantWorkStageSchema, candidateCount: z.number().int().min(0).max(100), coverage: z.literal('AUTHORIZED_NATIVE_ARTIFACT_METADATA'), total: z.null() }).strict(),
+};
+export const tenantWorkspaceToolSchemas = { ...tenantManagementToolSchemas, ...tenantWorkspaceExtraToolSchemas };
+export const tenantWorkspaceDataSchemas = { ...tenantManagementDataSchemas, ...tenantWorkspaceExtraDataSchemas };
+export function tenantWorkspaceScopesForInput(name, raw) { if (name === 'tenant_source_inventory') {
+    tenantWorkspaceExtraToolSchemas[name].parse(raw);
+    return ['knowledge.source.read'];
+} if (name === 'tenant_work_queue') {
+    tenantWorkspaceExtraToolSchemas[name].parse(raw);
+    return ['knowledge.workflow.read'];
+} return tenantManagementScopesForInput(name, raw); }
+export function tenantWorkspaceAuthorization(name) { return name === 'tenant_source_inventory' || name === 'tenant_work_queue' ? { selection: 'FIXED', scopeAlternatives: [[name === 'tenant_source_inventory' ? 'knowledge.source.read' : 'knowledge.workflow.read']] } : tenantManagementAuthorization(name); }
+export function tenantWorkspaceEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantWorkspaceDataSchemas[tool] }).strict(); }
+export const tenantWorkspaceInputJsonSchemas = Object.fromEntries(Object.entries(tenantWorkspaceToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const tenantWorkspaceOutputJsonSchemas = Object.fromEntries(Object.keys(tenantWorkspaceToolSchemas).map(name => [name, { type: 'object', oneOf: [z.toJSONSchema(tenantWorkspaceEnvelopeSchema(name), { target: 'draft-07' }), z.toJSONSchema(tenantManagementErrorSchema, { target: 'draft-07' })] }]));
+export const tenantWorkspaceProviderSchema = tenantManagementProviderBaseSchema.extend({ schemaVersion: z.literal(18), tools: z.array(z.string()).length(Object.keys(tenantWorkspaceToolSchemas).length), capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1'), z.literal('TENANT_WORKSPACE_METADATA_V1')]) }).strict().superRefine((value, ctx) => { if (new Set(value.tools).size !== Object.keys(tenantWorkspaceToolSchemas).length || value.tools.some(name => !Object.hasOwn(tenantWorkspaceToolSchemas, name)))
+    ctx.addIssue({ code: 'custom', message: 'Workspace tools must match the exact version18 contract' }); });

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

@@ -0,0 +1,37 @@
+/** Agent 的治理合同描述真实状态和下一步，不把写入权限解释为审核或正文权限。 */
+import { z } from 'zod';
+import { artifactStatusSchema, idSchema, isoDateTimeSchema, publicationReadinessReportSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+import { consumerProjectRefSchema } from './consumer.js';
+import { managementToolInputSchemas } from './management.js';
+const project = z.object({ projectRef: consumerProjectRefSchema }).strict();
+export const workflowPlanInputSchema = project.extend({ ref: stableUriSchema }).strict();
+export const workflowGuideInputSchema = project;
+export const workflowActionSchema = z.enum(['PREPARE_SOURCE', 'SUBMIT_REVIEW', 'FINALIZE_REVIEW', 'REGISTER']);
+export const workflowAdvanceInputSchema = workflowPlanInputSchema.extend({ action: workflowActionSchema, expectedVersion: z.number().int().nonnegative().optional(), actedAt: isoDateTimeSchema.optional() }).strict().superRefine((value, ctx) => {
+    if (['SUBMIT_REVIEW', 'FINALIZE_REVIEW'].includes(value.action) && (!value.expectedVersion || !value.actedAt))
+        ctx.addIssue({ code: 'custom', message: 'transition requires exact expectedVersion and actedAt' });
+});
+export const agentSubmitInputSchema = project.extend({ sourceId: idSchema, contentBase64: z.string().min(1).max(87384), mediaType: z.string().trim().min(1).max(256), access: z.enum(['PUBLIC', 'TENANT', 'INTERNAL', 'FDE_INTERNAL']).default('TENANT'), submittedAt: isoDateTimeSchema.optional(), freshnessSeconds: z.number().int().min(60).max(86400).optional() }).strict();
+const argumentsSchema = z.record(z.string(), z.json());
+export const workflowNextActionSchema = z.object({ id: z.string(), tool: z.string().nullable(), arguments: argumentsSchema, requiredScopes: z.array(z.string()), missingScopes: z.array(z.string()), missingFields: z.array(z.string()), canExecute: z.boolean(), automatic: z.boolean(), reasonCode: z.string(), cli: z.object({ command: z.string(), flags: argumentsSchema }).strict(), http: z.object({ method: z.literal('POST'), path: z.literal('/mcp/management'), tool: z.string().nullable() }).strict() }).strict();
+const readDecision = z.object({ action: z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']), reasonCodes: z.array(z.string()), authority: z.enum(['AUTHENTICATED_READER', 'LOCAL_PROFILE_SIMULATION']) }).strict();
+export const workflowPlanSchema = z.object({ schemaVersion: z.literal(1), projectRef: consumerProjectRefSchema, ref: stableUriSchema, contentHash: sha256Schema, kind: z.string(), version: z.number().int().positive().nullable(), status: artifactStatusSchema.or(z.enum(['RAW_EVIDENCE', 'RAW_MATERIAL'])), productionPhase: z.enum(['PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED']), rawMaterialAvailable: z.boolean().nullable(), readiness: publicationReadinessReportSchema.nullable(), reviewRef: stableUriSchema.nullable(), reviewDecision: z.enum(['PASS', 'REWORK', 'REJECT']).nullable(), support: z.object({ action: z.enum(['ALLOW', 'REVIEW_REQUIRED', 'DENY']), reasonCodes: z.array(z.string()), missingEvidenceRefs: z.array(stableUriSchema) }).strict().nullable(), governedPolicyReady: z.boolean(), consumerReadDecision: readDecision.nullable(), externalReady: z.boolean(), successorRef: stableUriSchema.nullable(), blockers: z.array(z.string()), nextActions: z.array(workflowNextActionSchema).max(70) }).strict();
+export const workflowAdvanceResultSchema = z.object({ schemaVersion: z.literal(1), action: workflowActionSchema, previousRef: stableUriSchema, inserted: z.boolean(), plan: workflowPlanSchema }).strict();
+export const workflowErrorSchema = z.object({ errorCode: z.string(), completedPhase: z.enum(['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED']).optional(), ref: stableUriSchema.optional() }).strict();
+export const workflowToolInputSchemas = { knowledge_workflow_guide: z.toJSONSchema(workflowGuideInputSchema, { target: 'draft-07' }), knowledge_workflow_plan: z.toJSONSchema(workflowPlanInputSchema, { target: 'draft-07' }), knowledge_workflow_advance: z.toJSONSchema(workflowAdvanceInputSchema, { target: 'draft-07' }), knowledge_agent_submit: z.toJSONSchema(agentSubmitInputSchema, { target: 'draft-07' }) };
+export const workflowToolScopes = { knowledge_workflow_guide: 'knowledge.workflow.read', knowledge_workflow_plan: 'knowledge.workflow.read', knowledge_workflow_advance: 'knowledge.workflow.read', knowledge_agent_submit: 'knowledge.material.write' };
+export const workflowActionScopes = { PREPARE_SOURCE: 'knowledge.compose', SUBMIT_REVIEW: 'knowledge.compose', FINALIZE_REVIEW: 'knowledge.approve', REGISTER: 'knowledge.material.write' };
+/** 网络成功和失败共享可发现 schema，阶段包含已经完成注册后的尾部失败。 */
+export const agentSubmitResultSchema = z.object({ schemaVersion: z.literal(1), production: z.object({ phase: z.enum(['CATALOG_PROJECTED', 'REGISTERED']), ref: stableUriSchema, registered: z.boolean(), identity: z.enum(['CONFIGURED', 'NOT_CONFIGURED']) }).strict(), presentation: z.object({ documentRef: stableUriSchema, inserted: z.boolean(), contentHash: sha256Schema }).strict().nullable(), evidenceRef: stableUriSchema, projectRef: consumerProjectRefSchema, contentHash: sha256Schema, byteLength: z.number().int().min(1).max(65536), inserted: z.boolean(), lifecycle: z.literal('QUEUED'), contentClass: z.literal('RAW_EVIDENCE'), nextStep: z.object({ tool: z.literal('knowledge_workflow_plan'), arguments: workflowPlanInputSchema }).strict() }).strict();
+const guideSchema = z.object({ schemaVersion: z.literal(1), model: z.record(z.string(), z.json()), rules: z.array(z.string()), tools: z.record(z.string(), z.object({ requiredScope: z.string(), inputSchema: z.json() }).strict()), advanceScopes: z.record(z.string(), z.string()), https: z.json() }).strict();
+const output = (success) => ({ type: 'object', oneOf: [z.toJSONSchema(success, { target: 'draft-07' }), z.toJSONSchema(workflowErrorSchema, { target: 'draft-07' })] });
+export const workflowToolOutputSchemas = { knowledge_workflow_guide: output(guideSchema), knowledge_workflow_plan: output(workflowPlanSchema), knowledge_workflow_advance: output(workflowAdvanceResultSchema), knowledge_agent_submit: output(agentSubmitResultSchema) };
+/** 同一份模型与参数 schema 供 CLI、MCP guide 和文档示例使用；不给 review 默认 PASS。 */
+export function workflowGuide() {
+    const tools = {};
+    for (const [name, schema] of Object.entries(workflowToolInputSchemas))
+        tools[name] = { requiredScope: workflowToolScopes[name], inputSchema: schema };
+    for (const [name, schema] of Object.entries(managementToolInputSchemas))
+        tools[name] = { requiredScope: name === 'knowledge_review' ? 'knowledge.review' : name === 'knowledge_finalize_review' ? 'knowledge.approve' : 'knowledge.compose', inputSchema: schema };
+    return { schemaVersion: 1, model: { raw: 'Evidence / Material 保留原字节和 provenance；原文可读不等于结论已审核。', reviewed: 'KNOWLEDGE / INSIGHT', lifecycle: ['DRAFT', 'READY_FOR_REVIEW', 'REVIEW(PASS|REWORK|REJECT)', 'APPROVED|REWORK_REQUIRED|REJECTED'], publication: ['PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED', 'consumer read ALLOW'] }, rules: ['先调用 knowledge_workflow_plan，再执行 canExecute 动作；缺字段由 Agent 补齐并重新计划。', '读取原文、核对引用和适用范围后，获授权 reviewer 显式写 PASS / REWORK / REJECT；不根据写入成功推断 PASS。', 'RESEARCH 先正式合成为 KNOWLEDGE / INSIGHT；Claim Currentness proposal 使用专门审核链。', 'freshnessSeconds 仅为作者在系统内首次保存的精确快照时效，不证明外部网页已复核；同身份重放不延长时效。', 'externalReady 需要注册、治理门通过及当前已鉴权消费者实际 read ALLOW；CLI profile 是模拟。', 'Plan 不提供正文或 Review summary；审核时使用独立 read scope 读取 exact ref。'], tools, advanceScopes: workflowActionScopes, https: { method: 'POST', path: '/mcp/management', body: { tool: 'tool name', arguments: '对应 inputSchema' }, authorization: 'OAuth Bearer + client/project binding；API key 不授予管理权限' } };
+}

package/dist/material-stream.js

@@ -0,0 +1,29 @@
+/** Streaming does not buffer large payloads; the whole-object hash is not a hash of a Range segment. */
+export async function materialStream(fetchImpl, url, token, options) {
+    const requested = options.range ? /^bytes=(\d*)-(\d*)$/.exec(options.range) : null;
+    if (options.range && (!requested || !requested[1] && !requested[2] || requested.slice(1).some(part => part !== '' && !Number.isSafeInteger(Number(part))) || !requested[1] && Number(requested[2]) === 0))
+        throw new Error('MATERIAL_STREAM_RANGE_INVALID');
+    const response = await fetchImpl(url, { method: options.head ? 'HEAD' : 'GET', headers: { authorization: `Bearer ${token}`, accept: 'application/octet-stream', ...(options.range ? { range: options.range } : {}) }, redirect: 'error', ...(options.signal ? { signal: options.signal } : {}) });
+    const fail = async (code) => { await response.body?.cancel(); throw new Error(code); };
+    if (response.status !== 200 && response.status !== 206)
+        return fail(`MATERIAL_STREAM_HTTP_${response.status}`);
+    const contentClass = response.headers.get('x-knowledge-content-class');
+    if (!contentClass || !['ARTIFACT_SNAPSHOT', 'RAW_EVIDENCE', 'RAW_EVIDENCE_MEDIA', 'REFERENCE_SNAPSHOT', 'REGISTERED_MATERIAL'].includes(contentClass))
+        return fail('MATERIAL_STREAM_CLASS_INVALID');
+    const hash = response.headers.get('x-knowledge-content-hash'), type = response.headers.get('content-type'), rawLength = response.headers.get('content-length'), contentRange = response.headers.get('content-range');
+    if (response.headers.get('x-knowledge-serving-action') !== 'ALLOW' || !hash || !/^sha256:[a-f0-9]{64}$/.test(hash) || !type || rawLength === null || !/^\d+$/.test(rawLength) || !Number.isSafeInteger(Number(rawLength)))
+        return fail('MATERIAL_STREAM_DESCRIPTOR_INVALID');
+    if (options.expectedContentHash && hash !== options.expectedContentHash)
+        return fail('MATERIAL_STREAM_IDENTITY_MISMATCH');
+    if (response.status === 206) {
+        const parts = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(contentRange ?? '');
+        if (!requested || !parts || parts.slice(1).some(part => !Number.isSafeInteger(Number(part))) || Number(parts[1]) > Number(parts[2]) || Number(parts[2]) - Number(parts[1]) + 1 !== Number(rawLength) || Number(parts[2]) >= Number(parts[3]))
+            return fail('MATERIAL_STREAM_RANGE_RESPONSE_INVALID');
+        const total = Number(parts[3]), start = requested[1] ? Number(requested[1]) : Math.max(0, total - Number(requested[2])), end = requested[1] && requested[2] ? Math.min(total - 1, Number(requested[2])) : total - 1;
+        if (start !== Number(parts[1]) || end !== Number(parts[2]))
+            return fail('MATERIAL_STREAM_RANGE_RESPONSE_INVALID');
+    }
+    if (!options.head && !response.body && Number(rawLength) > 0)
+        return fail('MATERIAL_STREAM_BODY_MISSING');
+    return { status: response.status, contentClass, contentHash: hash, mediaType: type, contentLength: Number(rawLength), contentRange, body: response.body, verification: 'SERVER_VERIFIED_BEFORE_HEADERS' };
+}

package/dist/{types/sdk/oauth.d.ts → oauth.d.ts}

@@ -1,10 +1,11 @@
-import { type SdkTransportOptions } from './transport.js';
+import { type TokenProvider } from './token-provider.js';
 import { type MaterialStreamOptions } from './material-stream.js';
-import { type KnowledgeMcpProviderContractV12 } from '../serving-contracts/index.js';
-import { type KnowledgeMcpProviderContractV11, type MaterialOutboxWindow, type KnowledgeMcpProviderContractV3, type KnowledgeMcpProviderContractV6, type KnowledgeMcpProviderContractV7, type KnowledgeMcpProviderContractV8, type KnowledgeMcpProviderContractV9, type KnowledgeMcpProviderContractV10, type OAuthMaterialPageResponse, type OAuthMaterialRoutePageResponse, type OAuthMaterialPartitionsResponse, type OAuthMaterialPartitionPageResponse, type OAuthMaterialPresentationResponse, type ServingDecision } from '../serving-contracts/index.js';
-export interface KnowledgeOAuthFileClientOptions extends SdkTransportOptions {
+import { type KnowledgeMcpProviderContractV12 } from './internal/serving-contracts/index.js';
+import { type KnowledgeMcpProviderContractV11, type MaterialOutboxWindow, type KnowledgeMcpProviderContractV3, type KnowledgeMcpProviderContractV6, type KnowledgeMcpProviderContractV7, type KnowledgeMcpProviderContractV8, type KnowledgeMcpProviderContractV9, type KnowledgeMcpProviderContractV10, type OAuthMaterialPageResponse, type OAuthMaterialRoutePageResponse, type OAuthMaterialPartitionsResponse, type OAuthMaterialPartitionPageResponse, type OAuthMaterialPresentationResponse, type ServingDecision } from './internal/serving-contracts/index.js';
+export interface KnowledgeOAuthFileClientOptions {
     baseUrl: string;
-    token: string;
+    token?: string;
+    tokenProvider?: TokenProvider;
     projectRef: string;
     fetchImpl?: typeof fetch;
     allowInsecureHttp?: boolean;
@@ -23,10 +24,9 @@ export type OAuthFileResult = {
     error: string;
 };
 export declare class KnowledgeOAuthFileClient {
-    private readonly limits;
     readonly projectRef: string;
     private readonly root;
-    private readonly token;
+    private readonly credentials;
     private readonly fetchImpl;
     private providerPromise;
     private materialProviderPromise;
@@ -59,19 +59,19 @@ export declare class KnowledgeOAuthFileClient {
                 sourceProjectKey: string;
                 identityHash: string;
                 kind: string;
-                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
                 mediaType: string;
                 decision: {
                     schemaVersion: 1;
                     action: "ALLOW" | "DENY";
-                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                     assessedAt: string;
                 };
             };
             materialAccess: {
                 schemaVersion: 1;
                 action: "ALLOW" | "DENY";
-                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                 assessedAt: string;
             };
             representation: {
@@ -81,7 +81,7 @@ export declare class KnowledgeOAuthFileClient {
                 contentHash: string | null;
                 mediaType: string;
                 byteLength: number | null;
-                methods: ("HEAD" | "GET")[];
+                methods: ("GET" | "HEAD")[];
                 range: "NONE" | "SINGLE";
                 verification: "ON_READ";
                 verificationChunkBytes: number | null;
@@ -105,19 +105,19 @@ export declare class KnowledgeOAuthFileClient {
                 sourceProjectKey: string;
                 identityHash: string;
                 kind: string;
-                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
                 mediaType: string;
                 decision: {
                     schemaVersion: 1;
                     action: "ALLOW" | "DENY";
-                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                     assessedAt: string;
                 };
             };
             materialAccess: {
                 schemaVersion: 1;
                 action: "ALLOW" | "DENY";
-                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                 assessedAt: string;
             };
             representation: {
@@ -127,7 +127,7 @@ export declare class KnowledgeOAuthFileClient {
                 contentHash: string | null;
                 mediaType: string;
                 byteLength: number | null;
-                methods: ("HEAD" | "GET")[];
+                methods: ("GET" | "HEAD")[];
                 range: "NONE" | "SINGLE";
                 verification: "ON_READ";
                 verificationChunkBytes: number | null;
@@ -166,7 +166,7 @@ export declare class KnowledgeOAuthFileClient {
                 contentHash: string | null;
                 mediaType: string;
                 byteLength: number | null;
-                methods: ("HEAD" | "GET")[];
+                methods: ("GET" | "HEAD")[];
                 range: "NONE" | "SINGLE";
                 verification: "ON_READ";
                 verificationChunkBytes: number | null;
@@ -232,12 +232,12 @@ export declare class KnowledgeOAuthFileClient {
                 sourceProjectKey: string;
                 identityHash: string;
                 kind: string;
-                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
                 mediaType: string;
                 decision: {
                     schemaVersion: 1;
                     action: "ALLOW" | "DENY";
-                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                     assessedAt: string;
                 };
             };