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

package/dist/resource.js

@@ -0,0 +1,123 @@
+import { AuthError } from './auth.js';
+import { authorizedFetch, tokenValue } from './token-provider.js';
+/** Provider 16 客户端：Tenant 默认，Project 仅为显式收窄；正文复用既有有界流合同。 */
+import { resourceToolSchemas, resourceDataSchemas, resourceEnvelopeSchema, resourceHttpContractSchema, materialTenantIdSchema } from './internal/contracts/index.js';
+import { materialStream } from './material-stream.js';
+export class ResourceSdkError extends Error {
+    code;
+    status;
+    recovery;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = 'ResourceSdkError';
+        this.recovery = /OUTBOX_RESYNC_REQUIRED|CURSOR_STALE/.test(code) ? 'CAPTURE_WINDOW_AND_REBOOTSTRAP' : null;
+    }
+}
+export class KnowledgeResourceClient {
+    options;
+    root;
+    basePath;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.baseUrl);
+        if (url.username || url.password || url.search || url.hash || !['https:', 'http:'].includes(url.protocol) || url.protocol === 'http:' && options.allowInsecureHttp !== true)
+            throw new Error('RESOURCE_SDK_BASE_URL_INVALID');
+        if (!options.tokenProvider && (typeof options.token !== 'string' || options.token.length < 16 || options.token.length > 4096 || /[\u0000-\u0020\u007f]/.test(options.token)))
+            throw new Error('RESOURCE_SDK_TOKEN_INVALID');
+        if (options.authentication !== undefined && options.authentication !== 'OAUTH' && options.authentication !== 'API_KEY')
+            throw new Error('RESOURCE_SDK_AUTHENTICATION_INVALID');
+        if (options.authentication === 'API_KEY')
+            materialTenantIdSchema.parse(options.tenantId);
+        if (options.expectedTenantId)
+            materialTenantIdSchema.parse(options.expectedTenantId);
+        this.root = url;
+        this.basePath = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+        this.fetchImpl = authorizedFetch(options.fetchImpl ?? fetch, options, url.origin);
+    }
+    url(operation) { const url = new URL(this.basePath + (this.options.authentication === 'API_KEY' ? '/v16/tenant/' : '/mcp/resources/') + operation, this.root.origin); if (this.options.authentication === 'API_KEY')
+        url.searchParams.set('tenantId', this.options.tenantId); return url; }
+    async request(url, options = {}) { try {
+        return await this.fetchImpl(url, { ...options, headers: { authorization: `Bearer ${await tokenValue(this.options)}`, accept: 'application/json', ...Object.fromEntries(new Headers(options.headers)) }, redirect: 'error' });
+    }
+    catch (error) {
+        if (error instanceof AuthError)
+            throw error;
+        throw new Error('RESOURCE_SDK_TRANSPORT_FAILURE');
+    } }
+    async json(response) {
+        if (!response.body)
+            throw new Error('RESOURCE_SDK_RESPONSE_INVALID');
+        const reader = response.body.getReader(), chunks = [];
+        let bytes = 0;
+        try {
+            while (true) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                bytes += part.value.byteLength;
+                if (bytes > 512 * 1024) {
+                    await reader.cancel();
+                    throw new Error('RESOURCE_SDK_RESULT_TOO_LARGE');
+                }
+                chunks.push(Buffer.from(part.value));
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        let raw;
+        try {
+            raw = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        }
+        catch {
+            throw new Error('RESOURCE_SDK_RESPONSE_INVALID');
+        }
+        if (!response.ok) {
+            const value = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw.errorCode : null;
+            throw new ResourceSdkError(typeof value === 'string' && /^[A-Z][A-Z0-9_]{1,100}$/.test(value) ? value : 'RESOURCE_SDK_HTTP_FAILURE', response.status);
+        }
+        return raw;
+    }
+    context(context, projectRef) {
+        const tenant = this.options.authentication === 'API_KEY' ? this.options.tenantId : this.options.expectedTenantId;
+        if ((tenant && context.tenantId !== tenant) || (projectRef ? (context.type !== 'PROJECT' || context.projectRef !== projectRef) : context.type !== 'TENANT'))
+            throw new Error('RESOURCE_SDK_CONTEXT_MISMATCH');
+    }
+    async tool(name, raw) {
+        if (!Object.hasOwn(resourceToolSchemas, name))
+            throw new Error('RESOURCE_SDK_OPERATION_UNSUPPORTED');
+        const input = resourceToolSchemas[name].parse(raw), body = JSON.stringify({ tool: name, arguments: input });
+        if (Buffer.byteLength(body) > 128 * 1024)
+            throw new Error('RESOURCE_SDK_REQUEST_TOO_LARGE');
+        const response = await this.request(this.url('call'), { method: 'POST', headers: { 'content-type': 'application/json' }, body }), envelope = resourceEnvelopeSchema.parse(await this.json(response));
+        this.context(envelope.context, input.projectRef);
+        return { ...envelope, data: resourceDataSchemas[name].parse(envelope.data) };
+    }
+    async contract(projectRef) { const input = resourceToolSchemas.knowledge_resource_window.parse(projectRef ? { projectRef } : {}), url = this.url('contract'); if (input.projectRef)
+        url.searchParams.set('projectRef', input.projectRef); const result = resourceHttpContractSchema.parse(await this.json(await this.request(url))); this.context(result.context, input.projectRef); return result; }
+    list(input = {}) { return this.tool('knowledge_resource_list', input); }
+    describe(ref, input = {}) { return this.tool('knowledge_resource_describe', { ...input, ref }); }
+    read(ref, input = {}) { return this.tool('knowledge_resource_read', { ...input, ref }); }
+    capabilities(ref, input = {}) { return this.tool('knowledge_resource_capabilities', { ...input, ref }); }
+    search(query, input = {}) { return this.tool('knowledge_resource_search', { ...input, query }); }
+    window(input = {}) { return this.tool('knowledge_resource_window', input); }
+    changes(input = {}) { return this.tool('knowledge_resource_changes', input); }
+    counts(input = {}) { return this.tool('knowledge_resource_counts', input); }
+    indexStatus(input = {}) { return this.tool('knowledge_resource_index_status', input); }
+    media(ref, input = {}) { return this.tool('knowledge_resource_media', { ...input, ref }); }
+    async stream(ref, options = {}) {
+        const input = resourceToolSchemas.knowledge_resource_read.parse({ ref, ...(options.projectRef ? { projectRef: options.projectRef } : {}) }), url = this.url('file');
+        if (options.head) {
+            url.searchParams.set('ref', input.ref);
+            if (input.projectRef)
+                url.searchParams.set('projectRef', input.projectRef);
+            return materialStream(this.fetchImpl, url, await tokenValue(this.options), options);
+        }
+        // POST 原件读取避免旧 ref 的 UTF-8 URL 膨胀；同一 Range、hash 与取消检查保持不变。
+        const post = (request, init) => this.fetchImpl(request, { ...init, method: 'POST', headers: { ...Object.fromEntries(new Headers(init?.headers)), 'content-type': 'application/json' }, body: JSON.stringify(input) });
+        return materialStream(post, url, await tokenValue(this.options), options);
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="node" />
+export { KnowledgeAuthClient, AuthError, type TenantSession } from './auth.js';
+export { tenantSessionSchema, tenantOperationStatusSchema } from './internal/serving-contracts/index.js';
+export { type TokenProvider, authorizedFetch, tokenValue } from './token-provider.js';

package/dist/session.js

@@ -0,0 +1,3 @@
+export { KnowledgeAuthClient, AuthError } from './auth.js';
+export { tenantSessionSchema, tenantOperationStatusSchema } from './internal/serving-contracts/index.js';
+export { authorizedFetch, tokenValue } from './token-provider.js';

package/dist/tenant-client.d.ts

@@ -0,0 +1,169 @@
+import { KnowledgeTenantWebWorkflowClient } from './tenant-web-workflow.js';
+import { KnowledgeResourceClient } from './resource.js';
+import { type KnowledgeTenantManagementClientOptions } from './tenant-management.js';
+export declare class TenantOperationUnknownError extends Error {
+    readonly requestId: string | undefined;
+    readonly code = "OPERATION_RESULT_UNKNOWN";
+    readonly completedPhase: string | undefined;
+    readonly ref: string | undefined;
+    constructor(requestId: string | undefined, details?: {
+        completedPhase?: string | undefined;
+        ref?: string | undefined;
+    });
+}
+export declare class KnowledgeTenantClient {
+    private o;
+    readonly resources: KnowledgeResourceClient;
+    readonly management: KnowledgeTenantWebWorkflowClient;
+    constructor(o: KnowledgeTenantManagementClientOptions);
+    call(name: string, input: unknown): Promise<{
+        schemaVersion: 1;
+        tenantId: string;
+        requestId: string;
+        state: "NOT_FOUND" | "INTENT_PERSISTED";
+        operationRef: string | null;
+        action: string | null;
+        receivedAt: string | null;
+        completion: "NOT_PROVEN";
+    } | {
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_runtime_status";
+        data: {
+            nodeId: string;
+            kind: "REQUESTS" | "RESOURCES" | "PROJECTIONS" | "PROJECTS";
+            observedAt: string;
+            coverage: "OWN_TENANT_METADATA_SAMPLE";
+            metadataOnly: true;
+            pageState: "UNAVAILABLE" | "READY";
+            items: ({
+                kind: "REQUESTS";
+                requestRef: string;
+                batchRef: string;
+                admission: "COMPLETED" | "PENDING" | "FAILED" | "STOPPED";
+                stopReason: "GRANT_REVOKED" | "DELEGATION_SUPERSEDED" | null;
+                executionAuthority: "UNAVAILABLE" | "CURRENT" | "BLOCKED" | "NOT_CONFIGURED" | "NOT_PENDING";
+                budgetReason: "READY" | "PAUSED" | "TENANT_UNCONFIGURED" | "HOST_IN_FLIGHT" | "TENANT_IN_FLIGHT" | "WORK_BUDGET" | "TIME_BUDGET" | "WORK_ACTIVE" | null;
+                captureRecord: "MISSING" | "UNAVAILABLE" | "PRESENT";
+                raw: {
+                    ref: string;
+                    contentHash: string | null;
+                    recordedBytes: number | null;
+                    manifest: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "PRESENT";
+                    blob: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "PRESENT_UNVERIFIED";
+                    contentHashReverified: false;
+                    catalog: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                    directory: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                    search: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                };
+                derivation: "REGISTERED" | "UNAVAILABLE" | "PENDING" | "NOT_REQUIRED";
+                completedPhase: "RAW_REGISTERED" | "DERIVED_REGISTERED" | null;
+                process: {
+                    runtimeNodeId: string;
+                    workloadId: string;
+                    runId: string;
+                    attribution: "COMPLETION_RUN" | "FAILURE_RUN" | "SOURCE_WORKLOAD_LATEST" | "PROJECT_WORKLOAD_LATEST";
+                    batchMatches: boolean | null;
+                    outcome: "FAILED" | "SUCCEEDED" | "TIMED_OUT" | "OUTPUT_LIMIT" | "SPAWN_FAILED" | "RECEIPT_MISSING" | null;
+                    receiptStatus: "BLOCKED" | "PARTIAL" | "FAILED" | "SUCCEEDED" | "SKIPPED" | null;
+                    durationMs: number | null;
+                    finishedAt: string;
+                    category: "NONE" | "OUTPUT_LIMIT" | "TIMEOUT" | "SPAWN_FAILURE" | "V8_HEAP_EXHAUSTED" | "NATIVE_ASSERTION_FAILURE" | "UNCAUGHT_EXCEPTION" | "PROCESS_SIGNAL" | "UNKNOWN_FAILURE" | null;
+                    peakRssBytes: number | null;
+                    sampleCount: number | null;
+                } | null;
+                failureCode?: "TENANT_SOURCE_HTTP_TERMINAL" | null | undefined;
+            } | {
+                ref: string;
+                contentHash: string | null;
+                recordedBytes: number | null;
+                manifest: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "PRESENT";
+                blob: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "PRESENT_UNVERIFIED";
+                contentHashReverified: false;
+                catalog: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                directory: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                search: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                kind: "RESOURCES";
+            } | {
+                ref: string;
+                contentHash: string | null;
+                recordedBytes: number | null;
+                manifest: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "PRESENT";
+                blob: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "PRESENT_UNVERIFIED";
+                contentHashReverified: false;
+                catalog: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                directory: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                search: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_REGISTERED" | "MATCH";
+                kind: "PROJECTIONS";
+                expectedManifestRevision: string;
+                preparedAt: string;
+            } | {
+                kind: "PROJECTS";
+                projectKey: string;
+                lifecycle: "ACTIVE" | "ARCHIVED";
+                runtimeState: "UNAVAILABLE" | "AVAILABLE";
+                projection: {
+                    requestedGeneration: number;
+                    completedGeneration: number;
+                    pendingGenerationDelta: number;
+                } | null;
+                checkpointState: "UNAVAILABLE" | "READY" | "EPOCH_MISMATCH";
+                directoryThroughSeq: number | null;
+                searchThroughSeq: number | null;
+                searchObservedMaxSeq: number | null;
+                searchSequenceDelta: number | null;
+                process: {
+                    runtimeNodeId: string;
+                    workloadId: string;
+                    runId: string;
+                    attribution: "COMPLETION_RUN" | "FAILURE_RUN" | "SOURCE_WORKLOAD_LATEST" | "PROJECT_WORKLOAD_LATEST";
+                    batchMatches: boolean | null;
+                    outcome: "FAILED" | "SUCCEEDED" | "TIMED_OUT" | "OUTPUT_LIMIT" | "SPAWN_FAILED" | "RECEIPT_MISSING" | null;
+                    receiptStatus: "BLOCKED" | "PARTIAL" | "FAILED" | "SUCCEEDED" | "SKIPPED" | null;
+                    durationMs: number | null;
+                    finishedAt: string;
+                    category: "NONE" | "OUTPUT_LIMIT" | "TIMEOUT" | "SPAWN_FAILURE" | "V8_HEAP_EXHAUSTED" | "NATIVE_ASSERTION_FAILURE" | "UNCAUGHT_EXCEPTION" | "PROCESS_SIGNAL" | "UNKNOWN_FAILURE" | null;
+                    peakRssBytes: number | null;
+                    sampleCount: number | null;
+                } | null;
+            })[];
+            nextAfter: string | null;
+            sampleCount: number;
+            total: null;
+            budget: {
+                state: "READY";
+                scope: "RUNTIME_OWNER_DATA_ROOT";
+                windowStart: string;
+                windowEnd: string;
+                usage: {
+                    inFlight: number;
+                    workUnits: number;
+                    runtimeMs: number;
+                };
+                limits: {
+                    tenantId: string;
+                    maxInFlight: number;
+                    maxWorkUnits: number;
+                    maxRuntimeMs: number;
+                    weight: number;
+                    paused: boolean;
+                };
+                maxWaitRounds: number;
+            } | {
+                state: "UNAVAILABLE" | "NOT_CONFIGURED";
+                reason: "CONFIGURATION_REQUIRED" | "TENANT_NOT_CONFIGURED" | "BINDING_MISMATCH" | "STATE_UNAVAILABLE";
+            };
+            delivery: {
+                headSeq: number;
+                retainedThroughSeq: number;
+                businessOutcome: "NOT_ASSERTED";
+            };
+        };
+    } | import("./resource.js").ResourceToolResponse<never> | {
+        schemaVersion: 2;
+        tenantId: string;
+        tool: never;
+        data?: never;
+    }>;
+    private dispatch;
+}

package/dist/tenant-client.js

@@ -0,0 +1,58 @@
+import { KnowledgeAuthClient } from './auth.js';
+import { tokenValue } from './token-provider.js';
+/** 统一客户端只组合既有 typed owner，不再实现一套工具或业务状态机。 */
+import { resourceToolSchemas } from './internal/contracts/index.js';
+import { tenantWebWorkflowToolSchemas, tenantWebContentToolSchemas, tenantProjectToolSchemas, tenantWorkspaceExtraToolSchemas } from './internal/serving-contracts/index.js';
+import { KnowledgeTenantWebWorkflowClient } from './tenant-web-workflow.js';
+import { KnowledgeResourceClient } from './resource.js';
+import { TenantManagementSdkError } from './tenant-management.js';
+const reads = new Set(['tenant_operation_status', 'tenant_workflow_guide', 'tenant_workflow_plan', 'tenant_knowledge_read', 'tenant_snapshot_status', 'tenant_material_routes', 'tenant_source_get', 'tenant_source_list', 'tenant_source_inventory', 'tenant_work_queue', 'tenant_project_list', 'tenant_project_get', 'tenant_project_materials', 'tenant_runtime_status', 'tenant_web_collect_preview', 'tenant_web_collect_status', 'tenant_web_collect_results', 'tenant_web_collect_cycles', 'tenant_web_collect_read', 'tenant_web_collect_index_status']);
+export class TenantOperationUnknownError extends Error {
+    requestId;
+    code = 'OPERATION_RESULT_UNKNOWN';
+    completedPhase;
+    ref;
+    constructor(requestId, details) {
+        super('OPERATION_RESULT_UNKNOWN');
+        this.requestId = requestId;
+        this.completedPhase = details?.completedPhase;
+        this.ref = details?.ref;
+    }
+}
+export class KnowledgeTenantClient {
+    o;
+    resources;
+    management;
+    constructor(o) {
+        this.o = o;
+        this.resources = new KnowledgeResourceClient(o);
+        this.management = new KnowledgeTenantWebWorkflowClient(o);
+    }
+    async call(name, input) { try {
+        return await this.dispatch(name, input);
+    }
+    catch (e) {
+        const code = e instanceof Error ? e.message : '';
+        if (!name.startsWith('knowledge_resource_') && !reads.has(name) && /TRANSPORT_FAILURE|RESPONSE_INVALID|HTTP_FAILURE/.test(code))
+            throw new TenantOperationUnknownError(input && typeof input === 'object' && 'requestId' in input && typeof input.requestId === 'string' ? input.requestId : undefined, e instanceof TenantManagementSdkError ? { completedPhase: e.completedPhase, ref: e.ref } : undefined);
+        throw e;
+    } }
+    async dispatch(name, input) {
+        const c = this.management;
+        if (name === 'tenant_operation_status')
+            return new KnowledgeAuthClient(this.o).operationStatus(await tokenValue(this.o), input, this.o.expectedTenantId);
+        if (Object.hasOwn(resourceToolSchemas, name))
+            return this.resources.tool(name, input);
+        if (Object.hasOwn(tenantWebWorkflowToolSchemas, name))
+            return c.workflowTool(name, input);
+        if (Object.hasOwn(tenantWebContentToolSchemas, name))
+            return c.webTool(name, input);
+        if (name === 'tenant_runtime_status')
+            return c.runtimeStatus(input);
+        if (Object.hasOwn(tenantProjectToolSchemas, name))
+            return c.projectTool(name, input);
+        if (Object.hasOwn(tenantWorkspaceExtraToolSchemas, name))
+            return c.workspaceTool(name, input);
+        return c.tool(name, input);
+    }
+}

package/dist/{types/sdk/tenant-management.d.ts → tenant-management.d.ts}

@@ -1,10 +1,11 @@
-import { type SdkTransportOptions } from './transport.js';
-import { tenantManagementErrorSchema, type TenantManagementToolName, type TenantManagementToolInput, type TenantManagementToolResponse } from '../serving-contracts/index.js';
+import { type TokenProvider } from './token-provider.js';
+import { tenantManagementErrorSchema, type TenantManagementToolName, type TenantManagementToolInput, type TenantManagementToolResponse } from './internal/serving-contracts/index.js';
 import { type MaterialStreamOptions } from './material-stream.js';
 type Failure = ReturnType<typeof tenantManagementErrorSchema.parse>;
-export interface KnowledgeTenantManagementClientOptions extends SdkTransportOptions {
+export interface KnowledgeTenantManagementClientOptions {
     baseUrl: string;
-    token: string;
+    token?: string;
+    tokenProvider?: TokenProvider;
     expectedTenantId: string;
     allowInsecureHttp?: boolean;
     fetchImpl?: typeof fetch;
@@ -21,7 +22,6 @@ export declare class TenantManagementSdkError<Phase extends string = NonNullable
 }
 export declare class KnowledgeTenantManagementClient {
     protected readonly options: KnowledgeTenantManagementClientOptions;
-    private readonly limits;
     private readonly root;
     private readonly path;
     private readonly fetchImpl;
@@ -180,7 +180,7 @@ export declare class KnowledgeTenantManagementClient {
             decision: {
                 schemaVersion: 1;
                 action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
-                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE" | "STALE" | "ACCESS_DENIED" | "ARTIFACT_NOT_APPROVED" | "ARTIFACT_SUPERSEDED" | "SEMANTIC_REVIEW_REQUIRED" | "SEMANTIC_DENIED" | "SEMANTIC_ADMISSION_MISSING" | "CURRENTNESS_MISSING" | "CURRENTNESS_REVIEW_REQUIRED" | "CURRENTNESS_DENIED" | "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" | "GOVERNANCE_NOT_CONFIGURED")[];
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE" | "STALE" | "ACCESS_DENIED" | "ARTIFACT_NOT_APPROVED" | "ARTIFACT_SUPERSEDED" | "SEMANTIC_REVIEW_REQUIRED" | "SEMANTIC_DENIED" | "SEMANTIC_ADMISSION_MISSING" | "CURRENTNESS_MISSING" | "CURRENTNESS_REVIEW_REQUIRED" | "CURRENTNESS_DENIED" | "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" | "GOVERNANCE_NOT_CONFIGURED")[];
                 assessedAt: string;
             };
             descriptor: {

package/dist/tenant-management.js

@@ -0,0 +1,149 @@
+import { AuthError } from './auth.js';
+import { authorizedFetch, tokenValue } from './token-provider.js';
+/** Provider17 客户端：Tenant 必填，Project/actor/authority 不进入请求上下文。 */
+import { materialTenantIdSchema, tenantResourceRefSchema } from './internal/contracts/index.js';
+import { tenantManagementToolSchemas, tenantManagementEnvelopeSchema, tenantManagementErrorSchema, tenantManagementProviderSchema, tenantManagementSafeErrorRef } from './internal/serving-contracts/index.js';
+import { materialStream } from './material-stream.js';
+export class TenantManagementSdkError extends Error {
+    code;
+    status;
+    completedPhase;
+    ref;
+    constructor(code, status, details) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = 'TenantManagementSdkError';
+        this.completedPhase = details?.completedPhase;
+        this.ref = details?.ref;
+    }
+}
+export class KnowledgeTenantManagementClient {
+    options;
+    root;
+    path;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        let url;
+        try {
+            url = new URL(options.baseUrl);
+        }
+        catch {
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_BASE_URL_INVALID', 0);
+        }
+        if (url.username || url.password || url.search || url.hash || !['https:', 'http:'].includes(url.protocol) || url.protocol === 'http:' && options.allowInsecureHttp !== true)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_BASE_URL_INVALID', 0);
+        materialTenantIdSchema.parse(options.expectedTenantId);
+        if (!options.tokenProvider && (typeof options.token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(options.token)))
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_TOKEN_INVALID', 0);
+        this.root = url;
+        this.path = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+        this.fetchImpl = authorizedFetch(options.fetchImpl ?? fetch, options, url.origin);
+    }
+    protocolVersion() { return 17; }
+    url(operation, version = this.protocolVersion()) { return new URL(this.path + (operation === 'provider' ? `/v${version}/provider` : `/v${version}/tenant/` + operation), this.root.origin); }
+    async request(url, init = {}) { try {
+        return await this.fetchImpl(url, { ...init, headers: { authorization: `Bearer ${await tokenValue(this.options)}`, accept: 'application/json', ...Object.fromEntries(new Headers(init.headers)) }, redirect: 'error' });
+    }
+    catch (error) {
+        if (error instanceof AuthError)
+            throw error;
+        throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_TRANSPORT_FAILURE', 0);
+    } }
+    failure(raw, status) { const failure = tenantManagementErrorSchema.safeParse(raw); if (!failure.success)
+        return null; const ref = tenantManagementSafeErrorRef(failure.data.ref, this.options.expectedTenantId); return new TenantManagementSdkError(failure.data.errorCode, status, { ...failure.data, ...(ref ? { ref } : { ref: undefined }) }); }
+    async json(response) {
+        if (!response.headers.get('content-type')?.toLowerCase().startsWith('application/json') || !response.body) {
+            await response.body?.cancel();
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status);
+        }
+        const reader = response.body.getReader(), chunks = [];
+        let bytes = 0;
+        try {
+            while (true) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                bytes += part.value.length;
+                if (bytes > 524288) {
+                    await reader.cancel();
+                    throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESULT_TOO_LARGE', response.status);
+                }
+                chunks.push(Buffer.from(part.value));
+            }
+        }
+        catch (error) {
+            if (error instanceof TenantManagementSdkError)
+                throw error;
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_TRANSPORT_FAILURE', response.status);
+        }
+        finally {
+            reader.releaseLock();
+        }
+        let raw;
+        try {
+            raw = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        }
+        catch {
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status);
+        }
+        const failure = this.failure(raw, response.status);
+        if (failure)
+            throw failure;
+        if (!response.ok)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status);
+        return raw;
+    }
+    async tool(name, raw, options = {}) {
+        if (!Object.hasOwn(tenantManagementToolSchemas, name))
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_OPERATION_UNSUPPORTED', 0);
+        const input = tenantManagementToolSchemas[name].parse(raw), body = JSON.stringify({ tool: name, arguments: input });
+        if (Buffer.byteLength(body) > 131072)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_REQUEST_TOO_LARGE', 0);
+        const response = await this.request(this.url('call'), { method: 'POST', headers: { 'content-type': 'application/json' }, body, ...(options.signal ? { signal: options.signal } : {}) }), result = tenantManagementEnvelopeSchema(name).safeParse(await this.json(response));
+        if (!result.success)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status);
+        if (result.data.tenantId !== this.options.expectedTenantId)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        return result.data;
+    }
+    async provider() { const response = await this.request(this.url('provider', 17)), result = tenantManagementProviderSchema.safeParse(await this.json(response)); if (!result.success)
+        throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status); return result.data; }
+    guide() { return this.tool('tenant_workflow_guide', {}); }
+    plan(ref) { return this.tool('tenant_workflow_plan', { ref }); }
+    read(ref) { return this.tool('tenant_knowledge_read', { ref }); }
+    snapshot(ref) { return this.tool('tenant_snapshot_status', { ref }); }
+    async stream(ref, options = {}) {
+        tenantResourceRefSchema.parse(ref);
+        const url = this.url('content');
+        url.searchParams.set('ref', ref);
+        const checked = async (input, init) => { let response; try {
+            response = await this.fetchImpl(input, { ...init, redirect: 'error' });
+        }
+        catch (error) {
+            if (error instanceof AuthError)
+                throw error;
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_TRANSPORT_FAILURE', 0);
+        } if (response.status !== 200 && response.status !== 206) {
+            await this.json(response);
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTENT_FAILURE', response.status);
+        } if (response.headers.get('x-knowledge-tenant-id') !== this.options.expectedTenantId) {
+            await response.body?.cancel();
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        } return response; };
+        try {
+            const result = await materialStream(checked, url, await tokenValue(this.options), options);
+            if (result.contentClass !== 'ARTIFACT_SNAPSHOT') {
+                await result.body?.cancel();
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', result.status);
+            }
+            return result;
+        }
+        catch (error) {
+            if (error instanceof TenantManagementSdkError)
+                throw error;
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTENT_FAILURE', 0);
+        }
+    }
+}

package/dist/{types/sdk/tenant-project.d.ts → tenant-project.d.ts}

@@ -1,4 +1,4 @@
-import { type TenantProjectToolName, type TenantProjectToolInput, type TenantProjectToolResponse } from '../serving-contracts/index.js';
+import { type TenantProjectToolName, type TenantProjectToolInput, type TenantProjectToolResponse } from './internal/serving-contracts/index.js';
 import { KnowledgeTenantWorkspaceClient } from './tenant-workspace.js';
 import { TenantManagementSdkError } from './tenant-management.js';
 import { type MaterialStreamOptions } from './material-stream.js';

package/dist/tenant-project.js

@@ -0,0 +1,63 @@
+import { tokenValue } from './token-provider.js';
+/** Explicit v19 Project context client; v17/v18 discovery and defaults remain available. */
+import { projectKeySchema, stableUriSchema, tenantProjectOperationRef } from './internal/contracts/index.js';
+import { tenantProjectToolSchemas, tenantProjectEnvelopeSchema, tenantProjectErrorSchema, tenantProjectProviderSchema, tenantManagementSafeErrorRef } from './internal/serving-contracts/index.js';
+import { KnowledgeTenantWorkspaceClient } from './tenant-workspace.js';
+import { TenantManagementSdkError } from './tenant-management.js';
+import { materialStream } from './material-stream.js';
+export class KnowledgeTenantProjectClient extends KnowledgeTenantWorkspaceClient {
+    protocolVersion() { return 19; }
+    failure(raw, status) { const failure = tenantProjectErrorSchema.safeParse(raw); if (!failure.success)
+        return null; const ref = tenantManagementSafeErrorRef(failure.data.ref, this.options.expectedTenantId); return new TenantManagementSdkError(failure.data.errorCode, status, { ...failure.data, ...(ref ? { ref } : { ref: undefined }) }); }
+    async projectTool(name, raw, options = {}) {
+        if (!Object.hasOwn(tenantProjectToolSchemas, name))
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_OPERATION_UNSUPPORTED', 0);
+        const input = tenantProjectToolSchemas[name].parse(raw), body = JSON.stringify({ tool: name, arguments: input });
+        if (Buffer.byteLength(body) > 131072)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_REQUEST_TOO_LARGE', 0);
+        const response = await this.request(this.url('call'), { method: 'POST', headers: { 'content-type': 'application/json' }, body, ...(options.signal ? { signal: options.signal } : {}) }), result = tenantProjectEnvelopeSchema(name).safeParse(await this.json(response));
+        if (!result.success)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status);
+        if (result.data.tenantId !== this.options.expectedTenantId)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        const data = result.data.data;
+        if ('projectKey' in input && data.projectKey !== input.projectKey)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        if ('requestId' in input && input.requestId) {
+            const expected = tenantProjectOperationRef(this.options.expectedTenantId, input.requestId);
+            if (data.operationRef && data.operationRef !== expected || data.receipt && data.receipt.operationRef !== expected)
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        }
+        return result.data;
+    }
+    async projectProvider() { const response = await this.request(this.url('provider', 19)), result = tenantProjectProviderSchema.safeParse(await this.json(response)); if (!result.success)
+        throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status); return result.data; }
+    async projectStream(projectKey, ref, options = {}) {
+        const checkedProject = projectKeySchema.parse(projectKey), checkedRef = stableUriSchema.parse(ref);
+        const url = this.url('content', 19);
+        url.pathname = url.pathname.replace(/\/tenant\/content$/, '/project/content');
+        url.searchParams.set('projectKey', checkedProject);
+        url.searchParams.set('ref', checkedRef);
+        const fetchImpl = this.options.fetchImpl ?? fetch;
+        const checked = async (input, init) => { let response; try {
+            response = await fetchImpl(input, { ...init, redirect: 'error' });
+        }
+        catch {
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_TRANSPORT_FAILURE', 0);
+        } if (response.status !== 200 && response.status !== 206) {
+            await this.json(response);
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTENT_FAILURE', response.status);
+        } if (response.headers.get('x-knowledge-tenant-id') !== this.options.expectedTenantId || response.headers.get('x-knowledge-project-key') !== checkedProject || response.headers.get('x-knowledge-authority-policy') !== 'TENANT_PROJECT_SCOPE') {
+            await response.body?.cancel();
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        } return response; };
+        try {
+            return { ...await materialStream(checked, url, await tokenValue(this.options), options), context: { tenantId: this.options.expectedTenantId, projectKey: checkedProject, policy: 'TENANT_PROJECT_SCOPE' } };
+        }
+        catch (error) {
+            if (error instanceof TenantManagementSdkError)
+                throw error;
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTENT_FAILURE', 0);
+        }
+    }
+}

package/dist/{types/sdk/tenant-runtime.d.ts → tenant-runtime.d.ts}

@@ -1,5 +1,5 @@
 /** 明确Provider20；仅此新client采用新registry，旧client默认保持原版本。 */
-import { type TenantRuntimeInput } from '../serving-contracts/index.js';
+import { type TenantRuntimeInput } from './internal/serving-contracts/index.js';
 import { KnowledgeTenantProjectClient } from './tenant-project.js';
 export declare class KnowledgeTenantRuntimeClient extends KnowledgeTenantProjectClient {
     protected protocolVersion(): 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25;