@native-knowledge/knowledge-sdk 0.0.0-stage → 0.1.0-rc.1

package/dist/types/sdk/agent-entry.d.ts

@@ -0,0 +1,291 @@
+import { agentGuidedEnvelopeSchema, type AgentGuidedDiscoveryInput, type AgentTaskInput } from '../serving-contracts/index.js';
+import { type ResourceToolName } from '../contracts/index.js';
+import { type BodySearchToolName, agentEntryEnvelopeSchema, agentCapabilityDataSchemas, type AgentDiscoveryInput, type AgentCapabilityName, type AgentCapabilityInput } from '../serving-contracts/index.js';
+import { KnowledgeTenantManagementClient, TenantManagementSdkError } from './tenant-management.js';
+import type { MaterialStreamOptions } from './material-stream.js';
+type Discovery = ReturnType<ReturnType<typeof agentEntryEnvelopeSchema<'knowledge_discover'>>['parse']>;
+export type AgentGuidedDiscovery = ReturnType<ReturnType<typeof agentGuidedEnvelopeSchema<'knowledge_discover'>>['parse']>;
+type GuidedExecution = ReturnType<ReturnType<typeof agentGuidedEnvelopeSchema<'knowledge_execute'>>['parse']>;
+type Execution = ReturnType<ReturnType<typeof agentEntryEnvelopeSchema<'knowledge_execute'>>['parse']>;
+type CapabilityResult<K extends AgentCapabilityName> = {
+    schemaVersion: 2;
+    data: ReturnType<(typeof agentCapabilityDataSchemas)[K]['parse']>;
+} & (K extends ResourceToolName | BodySearchToolName ? {
+    context: {
+        tenantId: string;
+        type: 'TENANT' | 'PROJECT';
+        projectRef?: string;
+    };
+    policy: string;
+} : {
+    tenantId: string;
+    tool: K;
+});
+export type AgentExecution<K extends AgentCapabilityName> = Omit<Execution, 'data'> & {
+    data: Omit<Execution['data'], 'result'> & {
+        result: CapabilityResult<K> | null;
+    };
+};
+export type AgentGuidedExecution<K extends AgentCapabilityName> = Omit<GuidedExecution, 'data'> & {
+    data: Omit<GuidedExecution['data'], 'result'> & {
+        result: CapabilityResult<K> | null;
+    };
+};
+export type AgentPageOptions = {
+    maxPages?: number;
+    signal?: AbortSignal;
+};
+export declare class KnowledgeAgentClient extends KnowledgeTenantManagementClient {
+    protected failure(raw: unknown, status: number): TenantManagementSdkError<string> | null;
+    private entry;
+    agentProvider(): Promise<{
+        provider: "knowledge-v2";
+        codeRevision: string;
+        authorityVersion: 2;
+        context: "TENANT_EXPLICIT_MANAGEMENT_V1";
+        managementConfigured: boolean;
+        resource: string;
+        issuer: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        revocationEndpoint: string;
+        mcpEndpoint: string;
+        callEndpoint: string;
+        contentEndpoint: string;
+        contentContextHeader: "x-knowledge-tenant-id";
+        legacyProviderEndpoint: string;
+        protocols: ("2026-07-28" | "2025-06-18")[];
+        requestMaxBytes: 131072;
+        resultMaxBytes: 524288;
+        submissionMaxBytes: 65536;
+        inlineContentMaxBytes: 32768;
+        contentReadMaxBytes: 16777216;
+        schemaVersion: 26;
+        collectionMode: "EXPLICIT_HOST_WITH_OPT_IN_DUE";
+        tools: ["knowledge_discover", "knowledge_execute"];
+        capabilities: ["AGENT_TASK_DISCOVERY_V1"];
+    }>;
+    discover(input?: AgentDiscoveryInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<Discovery>;
+    execute<K extends AgentCapabilityName>(tool: K, input: AgentCapabilityInput<K>, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExecution<K>>;
+    guidedDiscover(input?: AgentGuidedDiscoveryInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentGuidedDiscovery>;
+    planTask(task: AgentTaskInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "knowledge_discover";
+        data: {
+            nextActions: {
+                id: string;
+                title: string;
+                tool: "knowledge_discover" | "knowledge_execute";
+                arguments: Record<string, import("zod").JSONType>;
+                canExecute: boolean;
+                automatic: false;
+                missingFields: string[];
+                reasonCode: string;
+            }[];
+            items: {
+                name: "tenant_material_submit" | "tenant_artifact_draft" | "tenant_knowledge_compose" | "tenant_knowledge_review" | "tenant_artifact_promote" | "tenant_snapshot_declare" | "tenant_snapshot_status" | "tenant_material_share" | "tenant_material_revoke" | "tenant_material_routes" | "tenant_workflow_plan" | "tenant_workflow_advance" | "tenant_knowledge_read" | "tenant_source_define" | "tenant_source_configure" | "tenant_source_get" | "tenant_source_list" | "tenant_collection_request" | "tenant_collection_status" | "tenant_source_inventory" | "tenant_work_queue" | "tenant_project_list" | "tenant_project_get" | "tenant_project_materials" | "tenant_project_scope_set" | "tenant_project_lifecycle_set" | "tenant_runtime_status" | "tenant_web_collect_preview" | "tenant_web_collect_submit" | "tenant_web_collect_status" | "tenant_web_collect_results" | "tenant_web_collect_cycles" | "tenant_web_collect_control" | "tenant_web_collect_refresh" | "tenant_web_collect_read" | "tenant_web_collect_index_status" | "knowledge_resource_search_body" | "knowledge_resource_read_passage" | "knowledge_resource_list" | "knowledge_resource_describe" | "knowledge_resource_read" | "knowledge_resource_capabilities" | "knowledge_resource_search" | "knowledge_resource_window" | "knowledge_resource_changes" | "knowledge_resource_counts" | "knowledge_resource_index_status" | "knowledge_resource_media";
+                category: "materials" | "sources" | "collection" | "governance" | "sharing" | "projects" | "runtime";
+                title: string;
+                description: string;
+                readOnly: boolean;
+                scopeAlternatives: string[][];
+            }[];
+            nextAfter: string | null;
+            guidance: string;
+            categories: {
+                id: "materials" | "sources" | "collection" | "governance" | "sharing" | "projects" | "runtime";
+                title: string;
+                count: number;
+            }[];
+            detail: {
+                name: "tenant_material_submit" | "tenant_artifact_draft" | "tenant_knowledge_compose" | "tenant_knowledge_review" | "tenant_artifact_promote" | "tenant_snapshot_declare" | "tenant_snapshot_status" | "tenant_material_share" | "tenant_material_revoke" | "tenant_material_routes" | "tenant_workflow_plan" | "tenant_workflow_advance" | "tenant_knowledge_read" | "tenant_source_define" | "tenant_source_configure" | "tenant_source_get" | "tenant_source_list" | "tenant_collection_request" | "tenant_collection_status" | "tenant_source_inventory" | "tenant_work_queue" | "tenant_project_list" | "tenant_project_get" | "tenant_project_materials" | "tenant_project_scope_set" | "tenant_project_lifecycle_set" | "tenant_runtime_status" | "tenant_web_collect_preview" | "tenant_web_collect_submit" | "tenant_web_collect_status" | "tenant_web_collect_results" | "tenant_web_collect_cycles" | "tenant_web_collect_control" | "tenant_web_collect_refresh" | "tenant_web_collect_read" | "tenant_web_collect_index_status" | "knowledge_resource_search_body" | "knowledge_resource_read_passage" | "knowledge_resource_list" | "knowledge_resource_describe" | "knowledge_resource_read" | "knowledge_resource_capabilities" | "knowledge_resource_search" | "knowledge_resource_window" | "knowledge_resource_changes" | "knowledge_resource_counts" | "knowledge_resource_index_status" | "knowledge_resource_media";
+                inputSchema: import("zod").JSONType;
+                outputSchema: import("zod").JSONType;
+            } | null;
+            mode: "HOME" | "SEARCH" | "DETAIL" | "TASK";
+            inputHints: {
+                path: string;
+                kind: "MISSING" | "INVALID" | "UNSUPPORTED" | "CONFLICT";
+                expected: string;
+                prompt: string;
+                source: "USER_INPUT" | "CURRENT_STATE" | "PRIOR_RESULT" | "INDEPENDENT_REVIEW";
+                choices: import("zod").JSONType[];
+                constraints: Record<string, import("zod").JSONType>;
+            }[];
+            taskPlan: {
+                template: "RESEARCH_EXISTING" | "COLLECT_WEBSITE" | "INSPECT_COLLECTION" | "VERIFY_CITATION" | "PROJECT_RESEARCH" | "SHARE_MATERIAL" | "GOVERNANCE" | "UNRECOGNIZED";
+                status: "SUGGESTED_NOT_EXECUTED";
+                steps: {
+                    id: string;
+                    title: string;
+                    dependsOn: string[];
+                    capability: string | null;
+                    state: "READY" | "NEEDS_INPUT" | "NOT_AUTHORIZED" | "NEEDS_PRIOR_RESULT";
+                    action: {
+                        id: string;
+                        title: string;
+                        tool: "knowledge_discover" | "knowledge_execute";
+                        arguments: Record<string, import("zod").JSONType>;
+                        canExecute: boolean;
+                        automatic: false;
+                        missingFields: string[];
+                        reasonCode: string;
+                    } | null;
+                    inputHints: {
+                        path: string;
+                        kind: "MISSING" | "INVALID" | "UNSUPPORTED" | "CONFLICT";
+                        expected: string;
+                        prompt: string;
+                        source: "USER_INPUT" | "CURRENT_STATE" | "PRIOR_RESULT" | "INDEPENDENT_REVIEW";
+                        choices: import("zod").JSONType[];
+                        constraints: Record<string, import("zod").JSONType>;
+                    }[];
+                }[];
+                guidance: string;
+            } | null;
+        };
+    }>;
+    inputGuide(tool: AgentCapabilityName, input?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+        resupplyFields?: string[];
+    }): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "knowledge_discover";
+        data: {
+            nextActions: {
+                id: string;
+                title: string;
+                tool: "knowledge_discover" | "knowledge_execute";
+                arguments: Record<string, import("zod").JSONType>;
+                canExecute: boolean;
+                automatic: false;
+                missingFields: string[];
+                reasonCode: string;
+            }[];
+            items: {
+                name: "tenant_material_submit" | "tenant_artifact_draft" | "tenant_knowledge_compose" | "tenant_knowledge_review" | "tenant_artifact_promote" | "tenant_snapshot_declare" | "tenant_snapshot_status" | "tenant_material_share" | "tenant_material_revoke" | "tenant_material_routes" | "tenant_workflow_plan" | "tenant_workflow_advance" | "tenant_knowledge_read" | "tenant_source_define" | "tenant_source_configure" | "tenant_source_get" | "tenant_source_list" | "tenant_collection_request" | "tenant_collection_status" | "tenant_source_inventory" | "tenant_work_queue" | "tenant_project_list" | "tenant_project_get" | "tenant_project_materials" | "tenant_project_scope_set" | "tenant_project_lifecycle_set" | "tenant_runtime_status" | "tenant_web_collect_preview" | "tenant_web_collect_submit" | "tenant_web_collect_status" | "tenant_web_collect_results" | "tenant_web_collect_cycles" | "tenant_web_collect_control" | "tenant_web_collect_refresh" | "tenant_web_collect_read" | "tenant_web_collect_index_status" | "knowledge_resource_search_body" | "knowledge_resource_read_passage" | "knowledge_resource_list" | "knowledge_resource_describe" | "knowledge_resource_read" | "knowledge_resource_capabilities" | "knowledge_resource_search" | "knowledge_resource_window" | "knowledge_resource_changes" | "knowledge_resource_counts" | "knowledge_resource_index_status" | "knowledge_resource_media";
+                category: "materials" | "sources" | "collection" | "governance" | "sharing" | "projects" | "runtime";
+                title: string;
+                description: string;
+                readOnly: boolean;
+                scopeAlternatives: string[][];
+            }[];
+            nextAfter: string | null;
+            guidance: string;
+            categories: {
+                id: "materials" | "sources" | "collection" | "governance" | "sharing" | "projects" | "runtime";
+                title: string;
+                count: number;
+            }[];
+            detail: {
+                name: "tenant_material_submit" | "tenant_artifact_draft" | "tenant_knowledge_compose" | "tenant_knowledge_review" | "tenant_artifact_promote" | "tenant_snapshot_declare" | "tenant_snapshot_status" | "tenant_material_share" | "tenant_material_revoke" | "tenant_material_routes" | "tenant_workflow_plan" | "tenant_workflow_advance" | "tenant_knowledge_read" | "tenant_source_define" | "tenant_source_configure" | "tenant_source_get" | "tenant_source_list" | "tenant_collection_request" | "tenant_collection_status" | "tenant_source_inventory" | "tenant_work_queue" | "tenant_project_list" | "tenant_project_get" | "tenant_project_materials" | "tenant_project_scope_set" | "tenant_project_lifecycle_set" | "tenant_runtime_status" | "tenant_web_collect_preview" | "tenant_web_collect_submit" | "tenant_web_collect_status" | "tenant_web_collect_results" | "tenant_web_collect_cycles" | "tenant_web_collect_control" | "tenant_web_collect_refresh" | "tenant_web_collect_read" | "tenant_web_collect_index_status" | "knowledge_resource_search_body" | "knowledge_resource_read_passage" | "knowledge_resource_list" | "knowledge_resource_describe" | "knowledge_resource_read" | "knowledge_resource_capabilities" | "knowledge_resource_search" | "knowledge_resource_window" | "knowledge_resource_changes" | "knowledge_resource_counts" | "knowledge_resource_index_status" | "knowledge_resource_media";
+                inputSchema: import("zod").JSONType;
+                outputSchema: import("zod").JSONType;
+            } | null;
+            mode: "HOME" | "SEARCH" | "DETAIL" | "TASK";
+            inputHints: {
+                path: string;
+                kind: "MISSING" | "INVALID" | "UNSUPPORTED" | "CONFLICT";
+                expected: string;
+                prompt: string;
+                source: "USER_INPUT" | "CURRENT_STATE" | "PRIOR_RESULT" | "INDEPENDENT_REVIEW";
+                choices: import("zod").JSONType[];
+                constraints: Record<string, import("zod").JSONType>;
+            }[];
+            taskPlan: {
+                template: "RESEARCH_EXISTING" | "COLLECT_WEBSITE" | "INSPECT_COLLECTION" | "VERIFY_CITATION" | "PROJECT_RESEARCH" | "SHARE_MATERIAL" | "GOVERNANCE" | "UNRECOGNIZED";
+                status: "SUGGESTED_NOT_EXECUTED";
+                steps: {
+                    id: string;
+                    title: string;
+                    dependsOn: string[];
+                    capability: string | null;
+                    state: "READY" | "NEEDS_INPUT" | "NOT_AUTHORIZED" | "NEEDS_PRIOR_RESULT";
+                    action: {
+                        id: string;
+                        title: string;
+                        tool: "knowledge_discover" | "knowledge_execute";
+                        arguments: Record<string, import("zod").JSONType>;
+                        canExecute: boolean;
+                        automatic: false;
+                        missingFields: string[];
+                        reasonCode: string;
+                    } | null;
+                    inputHints: {
+                        path: string;
+                        kind: "MISSING" | "INVALID" | "UNSUPPORTED" | "CONFLICT";
+                        expected: string;
+                        prompt: string;
+                        source: "USER_INPUT" | "CURRENT_STATE" | "PRIOR_RESULT" | "INDEPENDENT_REVIEW";
+                        choices: import("zod").JSONType[];
+                        constraints: Record<string, import("zod").JSONType>;
+                    }[];
+                }[];
+                guidance: string;
+            } | null;
+        };
+    }>;
+    guidedExecute<K extends AgentCapabilityName>(tool: K, input: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentGuidedExecution<K>>;
+    private executeChecked;
+    openMaterialStream(ref: string, options?: MaterialStreamOptions & {
+        projectRef?: string;
+    }): Promise<import("./material-stream.js").MaterialStreamResponse>;
+    discoverPages(input: AgentDiscoveryInput, options?: {
+        maxPages?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "knowledge_discover";
+        data: {
+            mode: "HOME" | "SEARCH" | "DETAIL";
+            categories: {
+                id: "materials" | "sources" | "collection" | "governance" | "sharing" | "projects" | "runtime";
+                title: string;
+                count: number;
+            }[];
+            items: {
+                name: "tenant_material_submit" | "tenant_artifact_draft" | "tenant_knowledge_compose" | "tenant_knowledge_review" | "tenant_artifact_promote" | "tenant_snapshot_declare" | "tenant_snapshot_status" | "tenant_material_share" | "tenant_material_revoke" | "tenant_material_routes" | "tenant_workflow_plan" | "tenant_workflow_advance" | "tenant_knowledge_read" | "tenant_source_define" | "tenant_source_configure" | "tenant_source_get" | "tenant_source_list" | "tenant_collection_request" | "tenant_collection_status" | "tenant_source_inventory" | "tenant_work_queue" | "tenant_project_list" | "tenant_project_get" | "tenant_project_materials" | "tenant_project_scope_set" | "tenant_project_lifecycle_set" | "tenant_runtime_status" | "tenant_web_collect_preview" | "tenant_web_collect_submit" | "tenant_web_collect_status" | "tenant_web_collect_results" | "tenant_web_collect_cycles" | "tenant_web_collect_control" | "tenant_web_collect_refresh" | "tenant_web_collect_read" | "tenant_web_collect_index_status" | "knowledge_resource_search_body" | "knowledge_resource_read_passage" | "knowledge_resource_list" | "knowledge_resource_describe" | "knowledge_resource_read" | "knowledge_resource_capabilities" | "knowledge_resource_search" | "knowledge_resource_window" | "knowledge_resource_changes" | "knowledge_resource_counts" | "knowledge_resource_index_status" | "knowledge_resource_media";
+                category: "materials" | "sources" | "collection" | "governance" | "sharing" | "projects" | "runtime";
+                title: string;
+                description: string;
+                readOnly: boolean;
+                scopeAlternatives: string[][];
+            }[];
+            detail: {
+                name: "tenant_material_submit" | "tenant_artifact_draft" | "tenant_knowledge_compose" | "tenant_knowledge_review" | "tenant_artifact_promote" | "tenant_snapshot_declare" | "tenant_snapshot_status" | "tenant_material_share" | "tenant_material_revoke" | "tenant_material_routes" | "tenant_workflow_plan" | "tenant_workflow_advance" | "tenant_knowledge_read" | "tenant_source_define" | "tenant_source_configure" | "tenant_source_get" | "tenant_source_list" | "tenant_collection_request" | "tenant_collection_status" | "tenant_source_inventory" | "tenant_work_queue" | "tenant_project_list" | "tenant_project_get" | "tenant_project_materials" | "tenant_project_scope_set" | "tenant_project_lifecycle_set" | "tenant_runtime_status" | "tenant_web_collect_preview" | "tenant_web_collect_submit" | "tenant_web_collect_status" | "tenant_web_collect_results" | "tenant_web_collect_cycles" | "tenant_web_collect_control" | "tenant_web_collect_refresh" | "tenant_web_collect_read" | "tenant_web_collect_index_status" | "knowledge_resource_search_body" | "knowledge_resource_read_passage" | "knowledge_resource_list" | "knowledge_resource_describe" | "knowledge_resource_read" | "knowledge_resource_capabilities" | "knowledge_resource_search" | "knowledge_resource_window" | "knowledge_resource_changes" | "knowledge_resource_counts" | "knowledge_resource_index_status" | "knowledge_resource_media";
+                inputSchema: import("zod").JSONType;
+                outputSchema: import("zod").JSONType;
+            } | null;
+            nextAfter: string | null;
+            nextActions: {
+                id: string;
+                title: string;
+                tool: "knowledge_discover" | "knowledge_execute";
+                arguments: Record<string, import("zod").JSONType>;
+                canExecute: boolean;
+                automatic: false;
+                missingFields: string[];
+                reasonCode: string;
+            }[];
+            guidance: string;
+        };
+    }, void, unknown>;
+    pages(tool: 'tenant_project_get', input: AgentCapabilityInput<'tenant_project_get'>, options: AgentPageOptions & {
+        continuation: 'purpose' | 'selection';
+    }): AsyncGenerator<AgentExecution<'tenant_project_get'>, void, unknown>;
+    pages<K extends Exclude<AgentCapabilityName, 'tenant_project_get'>>(tool: K, input: AgentCapabilityInput<K>, options?: AgentPageOptions): AsyncGenerator<AgentExecution<K>, void, unknown>;
+}
+export {};

package/dist/types/sdk/agent-guidance-error.d.ts

@@ -0,0 +1,15 @@
+import { type AgentRecovery } from '../serving-contracts/index.js';
+import { TenantManagementSdkError } from './tenant-management.js';
+export declare function validateGuidanceActions(actions: AgentRecovery['nextActions'], options?: {
+    status?: number;
+    recoveryOnly?: boolean;
+}): void;
+export declare class KnowledgeAgentGuidanceError extends TenantManagementSdkError<string> {
+    readonly guidance: AgentRecovery;
+    constructor(code: string, status: number, guidance: AgentRecovery, details?: {
+        completedPhase?: string;
+        ref?: string;
+    });
+}
+/** Invalid optional guidance cannot erase a validated durable failure receipt. */
+export declare function agentGuidanceFailure(raw: unknown, status: number, tenantId: string): TenantManagementSdkError<string> | null;

package/dist/types/sdk/index.d.ts

@@ -0,0 +1,289 @@
+import { type SdkTransportOptions } from './transport.js';
+export type { SdkTransportOptions } from './transport.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+export * from './resource.js';
+export type { MaterialStreamOptions, MaterialStreamResponse } from './material-stream.js';
+export * from './oauth.js';
+import { type MaterialOutboxWindow, type ServingArtifactListResponse, type ServingArtifactPageResponse, type ServingArtifactMaterialPageResponse, type ServingArtifactMaterialResponse, type ServingMaterialPageResponse, type ServingMaterialRoutePageResponse, type ServingMaterialPartitionsResponse, type ServingMaterialPartitionPageResponse, type ServingMaterialSearchResponse, type ServingArtifactResponse, type ServingContentDecisionResponse, type ServingCurrentnessResponse, type ServingEvidenceListResponse, type ServingEvidencePageResponse, type ServingEvidencePresentationResponse, type ServingEvidenceResponse, type ServingHealthResponse, type ServingReferenceListResponse, type ServingReferenceLookupResponse, type ServingReferenceResponse, type ServingReferenceMaterialPageResponse, type ServingReferenceMaterialResponse, type ReferenceLookupFilter, type ServingProjectIntentResponse, type ServingProjectSourceListResponse, type ServingProjectSourceResponse, type ServingSourceResponse } from '../serving-contracts/index.js';
+export interface KnowledgeServingClientOptions extends SdkTransportOptions {
+    baseUrl: string;
+    token: string;
+    projectKey: string;
+    fetchImpl?: typeof fetch;
+    allowInsecureHttp?: boolean;
+}
+export interface ServingContentResponse {
+    decision: ServingContentDecisionResponse['decision'];
+    descriptor: {
+        contentHash: string;
+        mediaType: string;
+        byteLength: number;
+    };
+    content: Buffer;
+}
+export declare class KnowledgeServingClient {
+    private readonly limits;
+    readonly projectKey: string;
+    private readonly root;
+    private readonly basePath;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(options: KnowledgeServingClientOptions);
+    private url;
+    private request;
+    private json;
+    health(): Promise<ServingHealthResponse>;
+    listArtifacts(options?: {
+        kind?: string;
+        limit?: number;
+    }): Promise<ServingArtifactListResponse>;
+    pageArtifacts(options?: {
+        kind?: string;
+        limit?: number;
+        after?: string;
+    }): Promise<ServingArtifactPageResponse>;
+    pageArtifactMaterials(options?: {
+        kind?: string;
+        limit?: number;
+        after?: string;
+    }): Promise<ServingArtifactMaterialPageResponse>;
+    getMaterialOutboxWindow(): Promise<MaterialOutboxWindow>;
+    pageMaterials(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<ServingMaterialPageResponse>;
+    pageRouteMaterials(routeId: string, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<ServingMaterialRoutePageResponse>;
+    pageMaterialPartitions(options?: {
+        afterRouteId?: string;
+        limit?: number;
+    }): Promise<ServingMaterialPartitionsResponse>;
+    pageMaterialPartition(partition: 'OWNER' | 'LEGACY', options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<ServingMaterialPartitionPageResponse>;
+    searchMaterials(query: string, options?: {
+        afterId?: number;
+        limit?: number;
+        resourceType?: string;
+        sourceProjectKey?: string;
+    }): Promise<ServingMaterialSearchResponse>;
+    getArtifactMaterial(ref: string): Promise<ServingArtifactMaterialResponse>;
+    getArtifact(ref: string): Promise<ServingArtifactResponse>;
+    listEvidence(options?: {
+        sourceId?: string;
+        limit?: number;
+    }): Promise<ServingEvidenceListResponse>;
+    /** 通用采集文件目录按 ref 续页；fileDecision 控制原文件，contentDecision 控制受治理正文。 */
+    pageEvidence(options?: {
+        sourceId?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<ServingEvidencePageResponse>;
+    getEvidencePresentation(ref: string): Promise<ServingEvidencePresentationResponse>;
+    getEvidence(ref: string): Promise<ServingEvidenceResponse>;
+    getProjectIntent(): Promise<ServingProjectIntentResponse>;
+    listProjectSources(options?: {
+        enabled?: boolean;
+        limit?: number;
+    }): Promise<ServingProjectSourceListResponse>;
+    getProjectSource(sourceId: string): Promise<ServingProjectSourceResponse>;
+    getGovernanceSource(sourceId: string): Promise<ServingSourceResponse>;
+    getSource(sourceId: string): Promise<ServingSourceResponse>;
+    getCurrentness(ref: string): Promise<ServingCurrentnessResponse>;
+    listReferences(corpusKey: string, options?: {
+        recordType?: string;
+        limit?: number;
+    }): Promise<ServingReferenceListResponse>;
+    getReference(corpusKey: string, ref: string): Promise<ServingReferenceResponse>;
+    pageReferenceMaterials(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<ServingReferenceMaterialPageResponse>;
+    getReferenceMaterial(ref: string): Promise<ServingReferenceMaterialResponse>;
+    lookupReferences(options: ReferenceLookupFilter): Promise<ServingReferenceLookupResponse>;
+    private rawContent;
+    getMaterialContract(): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        authentication: "API_KEY";
+        resourceTypeMode: "OPEN_IDENTIFIER";
+        capabilitiesEndpoint: "/v3/material-capabilities";
+        capabilityPageEndpoint: "/v3/material-page";
+        fileEndpoint: "/v2/material-file";
+        mediaPageEndpoint: "/v3/material-media-page";
+        indexStatusEndpoint: "/v3/material-index-status";
+        fileMethods: ["GET", "HEAD"];
+        fileRange: "SINGLE";
+    }>;
+    getMaterialCapabilities(ref: string): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        material: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "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")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("HEAD" | "GET")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        };
+    }>;
+    pageMaterialCapabilities(options?: {
+        limit?: number;
+        after?: string;
+        resourceType?: string;
+        sourceProjectKey?: string;
+        refPrefix?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        items: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "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")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("HEAD" | "GET")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        }[];
+        nextAfter: string | null;
+    }>;
+    pageMaterialMedia(ref: string, options?: {
+        afterOrdinal?: number;
+        limit?: number;
+        documentRef?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        ref: string;
+        sourceContentHash: string;
+        documentRef: string | null;
+        documentContentHash: string | null;
+        state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+        items: {
+            ordinal: number;
+            kind: "IMAGE" | "AUDIO" | "VIDEO";
+            sourceUrl: string;
+            canonicalUrl: string | null;
+            availability: "UNAVAILABLE" | "MIRRORED" | "REMOTE_ONLY";
+            mediaRef: string | null;
+            contentHash: string | null;
+            mediaType: string | null;
+            byteLength: number | null;
+            state: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "READY" | "DENIED" | "REMOTE_ONLY";
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("HEAD" | "GET")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            } | null;
+        }[];
+        nextAfterOrdinal: number | null;
+    }>;
+    getMaterialIndexStatus(options?: {
+        afterSourceKey?: string;
+        afterNodeId?: string;
+        sourceProjectKey?: string;
+        limit?: number;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        queryCoverage: "DESCRIPTIVE_METADATA_V1";
+        indexedFields: ["TITLE", "SUMMARY"];
+        bodyIndexed: false;
+        semanticIndexed: false;
+        items: {
+            sourceProjectKey: string;
+            nodeId: string;
+            directoryThroughSeq: number;
+            searchThroughSeq: number | null;
+            observedMaxSeq: number | null;
+            checkpointUpdatedAt: string | null;
+            state: "PARTIAL_BACKFILL" | "SYNCED_AS_OF_CHECKPOINT";
+        }[];
+        nextAfter: {
+            sourceProjectKey: string;
+            nodeId: string;
+        } | null;
+    }>;
+    openMaterialStream(ref: string, options?: MaterialStreamOptions): Promise<import("./material-stream.js").MaterialStreamResponse>;
+    getMaterialFile(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getContent(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getArtifactFile(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getMedia(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getEvidenceMedia(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    /** 读取未经知识审核的原始 Evidence 文件；调用方仍需自己处理其时效与适用性。 */
+    getEvidenceFile(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+}
+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 './agent-entry.js';
+export * from './agent-guidance-error.js';

package/dist/types/sdk/material-stream.d.ts

@@ -0,0 +1,18 @@
+export interface MaterialStreamOptions {
+    range?: string;
+    head?: boolean;
+    signal?: AbortSignal;
+    expectedContentHash?: string;
+}
+export interface MaterialStreamResponse {
+    status: 200 | 206;
+    contentClass: string;
+    contentHash: string;
+    mediaType: string;
+    contentLength: number;
+    contentRange: string | null;
+    body: ReadableStream<Uint8Array> | null;
+    verification: 'SERVER_VERIFIED_BEFORE_HEADERS';
+}
+/** Streaming does not buffer large payloads; the whole-object hash is not a hash of a Range segment. */
+export declare function materialStream(fetchImpl: typeof fetch, url: URL, token: string, options: MaterialStreamOptions): Promise<MaterialStreamResponse>;