@native-knowledge/knowledge-sdk 0.0.0-stage → 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/tenant-management.d.ts

@@ -0,0 +1,240 @@
+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 {
+    baseUrl: string;
+    token?: string;
+    tokenProvider?: TokenProvider;
+    expectedTenantId: string;
+    allowInsecureHttp?: boolean;
+    fetchImpl?: typeof fetch;
+}
+export declare class TenantManagementSdkError<Phase extends string = NonNullable<Failure['completedPhase']>> extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly completedPhase: Phase | undefined;
+    readonly ref: string | undefined;
+    constructor(code: string, status: number, details?: {
+        completedPhase?: Phase | undefined;
+        ref?: string | undefined;
+    });
+}
+export declare class KnowledgeTenantManagementClient {
+    protected readonly options: KnowledgeTenantManagementClientOptions;
+    private readonly root;
+    private readonly path;
+    private readonly fetchImpl;
+    constructor(options: KnowledgeTenantManagementClientOptions);
+    protected protocolVersion(): 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26;
+    protected url(operation: 'provider' | 'call' | 'content', version?: 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26): import("url").URL;
+    protected request(url: URL, init?: RequestInit): Promise<Response>;
+    protected failure(raw: unknown, status: number): TenantManagementSdkError<string> | null;
+    protected json(response: Response): Promise<unknown>;
+    tool<K extends TenantManagementToolName>(name: K, raw: TenantManagementToolInput<K>, options?: {
+        signal?: AbortSignal;
+    }): Promise<TenantManagementToolResponse<K>>;
+    provider(): Promise<{
+        schemaVersion: 17;
+        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")[];
+        tools: string[];
+        requestMaxBytes: 131072;
+        resultMaxBytes: 524288;
+        submissionMaxBytes: 65536;
+        inlineContentMaxBytes: 32768;
+        contentReadMaxBytes: 16777216;
+        collectionMode: "MANUAL_ONLY_OAUTH";
+        capabilities: ["TENANT_MANAGEMENT_V1", "TENANT_WORKFLOW_V1", "TENANT_CURRENTNESS_V2", "TENANT_SOURCE_V1"];
+    }>;
+    guide(): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_workflow_guide";
+        data: {
+            schemaVersion: 2;
+            tenantId: string;
+            authorityVersion: 2;
+            scopes: string[];
+            tools: {
+                name: string;
+                authorization: {
+                    selection: "NEXT_STATUS" | "WORKFLOW_ACTION" | "FIXED";
+                    scopeAlternatives: string[][];
+                };
+                inputSchema: import("zod").JSONType;
+                outputSchema: import("zod").JSONType;
+            }[];
+            rules: string[];
+            limits: {
+                requestMaxBytes: 131072;
+                resultMaxBytes: 524288;
+                submissionMaxBytes: 65536;
+            };
+        };
+    }>;
+    plan(ref: string): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_workflow_plan";
+        data: {
+            schemaVersion: 2;
+            tenantId: string;
+            ref: string;
+            contentHash: string;
+            resourceType: string;
+            kind: string;
+            version: number;
+            status: "RAW_EVIDENCE" | "REFERENCE_SNAPSHOT" | "REGISTERED_MATERIAL" | "READY_FOR_REVIEW" | "REWORK_REQUIRED" | "APPROVED" | "REJECTED" | "DRAFT" | "GENERATED" | "SUPERSEDED" | "RAW_MATERIAL";
+            productionPhase: "REGISTERED";
+            readiness: {
+                schemaVersion: 2;
+                profile: "HUMAN_ARTICLE_V1" | "KNOWLEDGE_CARD_V1";
+                ready: boolean;
+                reasons: ("ROLE_MISMATCH" | "TITLE_REQUIRED" | "SUMMARY_REQUIRED" | "TEXT_TOO_SHORT" | "STRUCTURE_TOO_THIN" | "CITATION_COVERAGE_REQUIRED" | "MEDIA_UNAVAILABLE" | "SOURCE_REQUIRED" | "SOURCE_MISMATCH")[];
+                metrics: {
+                    textCharacters: number;
+                    blockCount: number;
+                    textBlockCount: number;
+                    mediaBlockCount: number;
+                    sourceCount: number;
+                    mediaEvidenceCount: number;
+                    citationCount: number;
+                    citedBlockCount: number;
+                };
+            } | null;
+            currentness: {
+                observedAt: string | null;
+                lastAttemptAt: string | null;
+                assessedAt: string;
+                state: "UNKNOWN" | "DUE" | "CURRENT" | "STALE" | "BLOCKED";
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCode: "CURRENT_WITHIN_CADENCE" | "REFRESH_DUE" | "STALE_AFTER_THRESHOLD" | "SOURCE_BLOCKED" | "SOURCE_CONTENT_CHANGED" | "NO_SUCCESSFUL_OBSERVATION";
+                policy: {
+                    schemaVersion: 1;
+                    dueAfterSeconds: number;
+                    staleAfterSeconds: number;
+                    staleAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    unknownAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    blockedAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                };
+                lastSuccessAt: string | null;
+                dueAt: string | null;
+                staleAt: string | null;
+                ageSeconds: number | null;
+                basis: "RETAINED_SNAPSHOT";
+                basisRef: string;
+                declarationRef: string;
+                tenantId: string;
+                subjectRef: string;
+                resourceType: string;
+                contentHash: string;
+                schemaVersion: 2;
+                subjectKind: "MATERIAL";
+                sourceRevisionRef?: string | undefined;
+            } | null;
+            governedPolicyReady: boolean;
+            consumerReadDecision: {
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCodes: string[];
+                authority: "AUTHENTICATED_READER" | "LOCAL_PROFILE_SIMULATION";
+            } | null;
+            externalReady: boolean;
+            successorRef: string | null;
+            blockers: string[];
+            nextActions: {
+                id: string;
+                tool: string | null;
+                arguments: Record<string, import("zod").JSONType>;
+                requiredScopes: string[];
+                missingScopes: string[];
+                missingFields: string[];
+                canExecute: boolean;
+                automatic: boolean;
+                reasonCode: string;
+            }[];
+        };
+    }>;
+    read(ref: string): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_knowledge_read";
+        data: {
+            schemaVersion: 2;
+            tenantId: string;
+            ref: string;
+            decision: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                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: {
+                contentHash: string;
+                mediaType: string;
+                byteLength: number;
+            } | null;
+            contentBase64: string | null;
+            truncated: boolean;
+            continuation: {
+                kind: "AUTHENTICATED_TENANT_GOVERNED_CONTENT";
+                ref: string;
+            } | null;
+        };
+    }>;
+    snapshot(ref: string): Promise<{
+        schemaVersion: 2;
+        tenantId: string;
+        tool: "tenant_snapshot_status";
+        data: {
+            subjectRef: string;
+            state: "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "READY" | "NOT_AVAILABLE" | "NOT_DECLARED" | "PROJECTION_PENDING";
+            assessment: {
+                observedAt: string | null;
+                lastAttemptAt: string | null;
+                assessedAt: string;
+                state: "UNKNOWN" | "DUE" | "CURRENT" | "STALE" | "BLOCKED";
+                action: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                reasonCode: "CURRENT_WITHIN_CADENCE" | "REFRESH_DUE" | "STALE_AFTER_THRESHOLD" | "SOURCE_BLOCKED" | "SOURCE_CONTENT_CHANGED" | "NO_SUCCESSFUL_OBSERVATION";
+                policy: {
+                    schemaVersion: 1;
+                    dueAfterSeconds: number;
+                    staleAfterSeconds: number;
+                    staleAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    unknownAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                    blockedAction: "ALLOW" | "DENY" | "REVIEW_REQUIRED";
+                };
+                lastSuccessAt: string | null;
+                dueAt: string | null;
+                staleAt: string | null;
+                ageSeconds: number | null;
+                basis: "RETAINED_SNAPSHOT";
+                basisRef: string;
+                declarationRef: string;
+                tenantId: string;
+                subjectRef: string;
+                resourceType: string;
+                contentHash: string;
+                schemaVersion: 2;
+                subjectKind: "MATERIAL";
+                sourceRevisionRef?: string | undefined;
+            } | null;
+        };
+    }>;
+    stream(ref: string, options?: MaterialStreamOptions): Promise<import("./material-stream.js").MaterialStreamResponse>;
+}
+export {};