@native-knowledge/cli 0.1.0-rc.1 → 0.1.0-rc.3

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

@@ -0,0 +1,55 @@
+/** 可执行静态网站任务；独立于冻结的 S1 意图，Tenant 是唯一归属。 */
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { tenantStorageKey } from './resource-scope.js';
+import { tenantWebIntentSchema, tenantWebUrlSchema, tenantWebJobRefSchema, tenantWebCanonical } from './tenant-web-collection.js';
+import { tenantSourceSemanticsSchema } from './tenant-source.js';
+import { tenantCollectionCaptureSchema, tenantCollectionCycleSchema } from './tenant-collection.js';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+export const TENANT_WEB_CRAWL_CAPABILITY = 'TENANT_WEB_CRAWL_V1';
+export const tenantWebPolicySchema = tenantSourceSemanticsSchema.shape.sourcePolicy.refine(v => v.acquisition === 'ALLOW' && v.propagation === 'TENANT_ONLY');
+export const tenantWebCrawlSchema = z.object({ schemaVersion: z.literal(2), intent: tenantWebIntentSchema, policy: tenantWebPolicySchema }).strict();
+export function tenantWebAdmissionKey(tenantId, jobRef) { tenantWebJobRefSchema.parse(jobRef); if (new URL(jobRef).hostname !== tenantStorageKey(tenantId))
+    throw new Error('TENANT_WEB_SCOPE_FORBIDDEN'); return createHash('sha256').update(JSON.stringify(['TENANT_WEB_ADMISSION_V1', tenantId, jobRef])).digest('hex'); }
+export const tenantWebTargetSchema = z.object({ ordinal: z.number().int().min(0).max(9999), url: tenantWebUrlSchema, parent: tenantWebUrlSchema.nullable(), depth: z.number().int().min(0).max(10), role: z.enum(['PAGE', 'SITEMAP', 'FEED']) }).strict();
+export const tenantWebOutcomeSchema = z.object({ ordinal: tenantWebTargetSchema.shape.ordinal, batchId: z.string().regex(/^batch_[a-f0-9]{64}$/).nullable(), capture: tenantCollectionCaptureSchema.nullable(), registered: z.boolean(), errorCode: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).nullable(), reused: z.boolean() }).strict().refine(v => !v.registered || v.capture !== null);
+export const tenantWebHeadSchema = z.object({ schemaVersion: z.literal(1), seq: z.number().int().nonnegative(), queued: z.number().int().min(0).max(10000), cursor: z.number().int().min(0).max(10000), stage: z.enum(['ACQUIRE', 'DISCOVER']), after: z.number().int().nonnegative(), attempts: z.number().int().min(0).max(3), currentAcquired: z.boolean(), acquired: z.number().int().min(0).max(10000), registered: z.number().int().min(0).max(10000), chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), reservation: z.object({ bytes: z.number().int().nonnegative(), ms: z.number().int().nonnegative() }).strict().nullable(), gaps: z.array(z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/)).max(32), state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL']), finishedAt: isoDateTimeSchema.nullable(), notBefore: isoDateTimeSchema.nullable() }).strict().refine(v => v.cursor <= v.queued && v.registered <= v.acquired && v.acquired <= v.queued && (['COMPLETE', 'PARTIAL'].includes(v.state) === (v.finishedAt !== null)) && (!v.reservation || v.state === 'RUNNING' && v.chargedBytes >= v.reservation.bytes && v.chargedMs >= v.reservation.ms) && (!v.notBefore || v.state === 'RUNNING' && !v.reservation) && (v.state !== 'PARTIAL' || v.gaps.length > 0) && (v.state !== 'COMPLETE' || v.queued > 0 && v.cursor === v.queued && v.gaps.length === 0 && v.registered === v.queued && !v.reservation && !v.notBefore));
+export const tenantWebChildOwnerSchema = z.object({ schemaVersion: z.literal(1), jobRef: tenantWebJobRefSchema, ordinal: tenantWebTargetSchema.shape.ordinal, requestId: tenantCollectionCycleSchema, batchId: z.string().regex(/^batch_[a-f0-9]{64}$/) }).strict();
+export const tenantWebCrawlStatusSchema = z.object({ requestId: tenantCollectionCycleSchema, jobRef: tenantWebJobRefSchema, specRevision: sha256Schema, state: tenantWebHeadSchema.shape.state, phase: z.literal('STATIC_ACQUISITION'), requirementsState: z.literal('DECLARED_NOT_EVALUATED'), indexState: z.literal('NOT_EVALUATED'), coverage: z.object({ total: z.number().int().nonnegative().nullable(), discovered: z.number().int().nonnegative(), acquired: z.number().int().nonnegative(), registered: z.number().int().nonnegative(), pending: z.number().int().nonnegative(), gaps: tenantWebHeadSchema.shape.gaps }).strict(), budget: z.object({ chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), conservativeReservation: z.boolean() }).strict(), finishedAt: isoDateTimeSchema.nullable(), nextEligibleAt: isoDateTimeSchema.nullable() }).strict();
+export function tenantWebCrawlStatus(job, head) { return tenantWebCrawlStatusSchema.parse({ requestId: job.intent.requestId, jobRef: job.intent.jobRef, specRevision: job.intent.specRevision, state: head.state, phase: 'STATIC_ACQUISITION', requirementsState: 'DECLARED_NOT_EVALUATED', indexState: 'NOT_EVALUATED', coverage: { total: head.state === 'COMPLETE' ? head.queued : null, discovered: head.queued, acquired: head.acquired, registered: head.registered, pending: head.queued - head.cursor, gaps: head.gaps }, budget: { chargedBytes: head.chargedBytes, chargedMs: head.chargedMs, conservativeReservation: head.reservation !== null }, finishedAt: head.finishedAt, nextEligibleAt: head.notBefore }); }
+export function tenantWebPathMatches(pattern, pathname) { return pattern.endsWith('/**') ? (pathname === pattern.slice(0, -3) || pathname.startsWith(pattern.slice(0, -2))) : pathname === pattern; }
+export function tenantWebInScope(spec, raw, options = {}) {
+    const parsed = tenantWebUrlSchema.safeParse(raw);
+    if (!parsed.success)
+        return false;
+    const url = new URL(parsed.data), scope = spec.scope;
+    if (!scope.allowedOrigins.includes(url.origin))
+        return false;
+    if (options.robots)
+        return url.pathname === '/robots.txt' && !url.search;
+    let pathname;
+    try {
+        pathname = decodeURIComponent(url.pathname);
+    }
+    catch {
+        return false;
+    }
+    if (/[\\\x00-\x1f]/.test(pathname) || /%[0-9a-f]{2}/i.test(pathname))
+        return false;
+    // GitLab and similar public APIs encode a slash inside an identifier. Only an exact
+    // caller-listed URL without path filters can use it; section/prefix matching stays closed.
+    if (/%2f/i.test(url.pathname) && (!['SINGLE_PAGE', 'URL_LIST'].includes(scope.mode) || scope.includePaths.length > 0 || scope.excludePaths.length > 0))
+        return false;
+    if (scope.excludePaths.some(p => tenantWebPathMatches(p, pathname)))
+        return false;
+    if (options.bootstrap && raw === spec.url && ['SITEMAP', 'FEED'].includes(scope.mode))
+        return true;
+    if (scope.includePaths.length && !scope.includePaths.some(p => tenantWebPathMatches(p, pathname)))
+        return false;
+    if (scope.mode === 'SINGLE_PAGE')
+        return raw === spec.url;
+    if (scope.mode === 'URL_LIST')
+        return raw === spec.url || scope.urls.includes(raw);
+    return true;
+}
+export function sameTenantWebDelegation(a, b) { return a.intent.tenantId === b.intent.tenantId && tenantWebCanonical(a.policy) === tenantWebCanonical(b.policy) && tenantWebCanonical(a.intent.authority) === tenantWebCanonical(b.intent.authority) && tenantWebCanonical(a.intent.actor) === tenantWebCanonical(b.intent.actor); }

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

@@ -0,0 +1,68 @@
+/** S3 opt-in contracts. Frozen Provider21/22 objects are never silently upgraded. */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { tenantWebSpecSchema, tenantWebIntentSchema, tenantWebCanonical, tenantWebJobRef, tenantWebUrlSchema } from './tenant-web-collection.js';
+import { tenantWebPolicySchema, tenantWebTargetSchema, tenantWebOutcomeSchema, tenantWebHeadSchema, tenantWebChildOwnerSchema, tenantWebCrawlStatusSchema, tenantWebInScope } from './tenant-web-crawl.js';
+import { parseTenantResourceRef, tenantStorageKey, tenantResourceRefs } from './resource-scope.js';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+export const TENANT_WEB_DYNAMIC_CAPABILITY = 'TENANT_WEB_DYNAMIC_V1';
+const selector = z.string().trim().min(1).max(512).refine(s => !s.includes('\0'));
+const origin = tenantWebUrlSchema.refine(s => new URL(s).origin === s);
+export const tenantWebRenderSchema = z.object({
+    mode: z.enum(['HTTP_ONLY', 'AUTO', 'ALWAYS']).default('HTTP_ONLY'),
+    requiredSelector: selector.nullable().default(null), minTextChars: z.number().int().min(0).max(100000).default(80),
+    resourceOrigins: z.array(origin).max(16).default([]),
+    interaction: z.object({ kind: z.enum(['NONE', 'NEXT_PAGE', 'LOAD_MORE', 'SCROLL']), selector: selector.nullable().default(null), endSelector: selector.nullable().default(null), maxSteps: z.number().int().min(0).max(100).default(0) }).strict().default({ kind: 'NONE', selector: null, endSelector: null, maxSteps: 0 }),
+}).strict().superRefine((v, c) => {
+    if (v.interaction.kind !== 'NONE' && (v.mode === 'HTTP_ONLY' || v.interaction.maxSteps === 0))
+        c.addIssue({ code: 'custom', message: 'Interactions require a browser and a positive step bound' });
+    if (['NEXT_PAGE', 'LOAD_MORE'].includes(v.interaction.kind) && !v.interaction.selector)
+        c.addIssue({ code: 'custom', message: 'Button interactions require a selector' });
+    if (v.interaction.kind === 'NONE' && v.interaction.maxSteps !== 0)
+        c.addIssue({ code: 'custom', message: 'NONE cannot request actions' });
+    if (new Set(v.resourceOrigins).size !== v.resourceOrigins.length)
+        c.addIssue({ code: 'custom', message: 'Resource origins must be unique' });
+});
+export const tenantWebDynamicSpecSchema = z.object({ ...tenantWebSpecSchema.shape, schemaVersion: z.literal(2), render: tenantWebRenderSchema.default({ mode: 'HTTP_ONLY', requiredSelector: null, minTextChars: 80, resourceOrigins: [], interaction: { kind: 'NONE', selector: null, endSelector: null, maxSteps: 0 } }) }).strict().superRefine((v, c) => {
+    const { render: ignored, ...base } = v;
+    const old = tenantWebSpecSchema.safeParse({ ...base, schemaVersion: 1 });
+    if (!old.success)
+        for (const issue of old.error.issues)
+            c.addIssue({ ...issue, path: issue.path });
+    if (v.render.interaction.maxSteps > v.limits.maxInteractions)
+        c.addIssue({ code: 'custom', message: 'Page actions exceed the job interaction budget' });
+    if (v.render.interaction.kind === 'NEXT_PAGE' && !v.scope.followPagination)
+        c.addIssue({ code: 'custom', message: 'NEXT_PAGE requires pagination scope' });
+});
+export const tenantWebDynamicSpecRevision = (v) => 'sha256:' + createHash('sha256').update(tenantWebCanonical(tenantWebDynamicSpecSchema.parse(v))).digest('hex');
+export const tenantWebDynamicIntentSchema = z.object({ ...tenantWebIntentSchema.shape, schemaVersion: z.literal(2), requestedSpec: tenantWebDynamicSpecSchema, spec: tenantWebDynamicSpecSchema }).strict().superRefine((v, c) => {
+    if (v.actor.tenantId !== v.tenantId || v.jobRef !== tenantWebJobRef(v.tenantId, v.requestId) || v.specRevision !== tenantWebDynamicSpecRevision(v.spec) || v.inputRevision !== tenantWebDynamicSpecRevision(v.requestedSpec))
+        c.addIssue({ code: 'custom', message: 'Frozen Tenant intent identity mismatch' });
+    if (v.spec.limits.maxResourceBytes > Math.min(v.requestedSpec.limits.maxResourceBytes, v.requestedSpec.limits.maxTotalBytes) || tenantWebCanonical({ ...v.spec, limits: { ...v.spec.limits, maxResourceBytes: v.requestedSpec.limits.maxResourceBytes } }) !== tenantWebCanonical(v.requestedSpec))
+        c.addIssue({ code: 'custom', message: 'Only resource limit narrowing is permitted' });
+});
+export const tenantWebDynamicJobSchema = z.object({ schemaVersion: z.literal(3), intent: tenantWebDynamicIntentSchema, policy: tenantWebPolicySchema }).strict();
+export const tenantWebDynamicTargetSchema = z.object({ ...tenantWebTargetSchema.shape, ordinal: z.number().int().min(0).max(10999), role: z.enum(['PAGE', 'SITEMAP', 'FEED', 'ATTACHMENT']), attachment: z.enum(['PDF', 'IMAGE', 'AUDIO', 'VIDEO', 'OTHER']).nullable().default(null) }).strict().refine(v => (v.role === 'ATTACHMENT') === (v.attachment !== null));
+export const tenantWebDynamicOutcomeSchema = z.object({ ...tenantWebOutcomeSchema.shape, ordinal: tenantWebDynamicTargetSchema.shape.ordinal }).strict().refine(v => !v.registered || v.capture !== null);
+const count = z.number().int().min(0).max(11000);
+export const tenantWebDynamicHeadSchema = z.object({ ...tenantWebHeadSchema.shape,
+    schemaVersion: z.literal(2), queued: count, cursor: count, acquired: count, registered: count,
+    phase: z.enum(['RENDER', 'LINKS', 'PDF']).default('RENDER'), renderIndex: z.number().int().min(0).max(101), linkState: z.number().int().min(-1).max(101),
+    browserPages: z.number().int().min(0).max(10000), pagesQueued: z.number().int().min(0).max(10000), filesQueued: z.number().int().min(0).max(1000), renderedStates: count, pdfExtracted: z.number().int().min(0).max(1000), interactions: z.number().int().min(0).max(1000),
+    reservation: z.object({ bytes: z.number().int().nonnegative(), ms: z.number().int().nonnegative(), interactions: z.number().int().min(0).max(1000) }).strict().nullable(),
+}).strict().refine(v => v.queued === v.pagesQueued + v.filesQueued && v.cursor <= v.queued && v.registered <= v.acquired && v.acquired <= v.queued && (['COMPLETE', 'PARTIAL'].includes(v.state) === (v.finishedAt !== null)) && (!v.reservation || v.state === 'RUNNING' && v.chargedBytes >= v.reservation.bytes && v.chargedMs >= v.reservation.ms && v.interactions >= v.reservation.interactions) && (!v.notBefore || v.state === 'RUNNING' && !v.reservation) && (v.state !== 'PARTIAL' || v.gaps.length > 0) && (v.state !== 'COMPLETE' || v.queued > 0 && v.cursor === v.queued && v.gaps.length === 0 && v.registered === v.queued && !v.reservation && !v.notBefore));
+export const tenantWebDynamicChildOwnerSchema = z.object({ ...tenantWebChildOwnerSchema.shape, schemaVersion: z.literal(2), ordinal: tenantWebDynamicTargetSchema.shape.ordinal }).strict();
+export const tenantWebDynamicStatusSchema = z.object({ ...tenantWebCrawlStatusSchema.shape, phase: z.literal('DYNAMIC_ACQUISITION'), ocr: z.object({ capability: z.literal('UNAVAILABLE'), budgetState: z.literal('NOT_CONFIGURED'), processedPages: z.literal(0) }).strict(), dynamic: z.object({ browserPages: z.number().int().nonnegative(), pagesQueued: z.number().int().nonnegative(), filesQueued: z.number().int().nonnegative(), renderedStates: z.number().int().nonnegative(), pdfExtracted: z.number().int().nonnegative(), interactions: z.number().int().nonnegative() }).strict() }).strict();
+export function tenantWebDynamicStatus(job, h) { return tenantWebDynamicStatusSchema.parse({ requestId: job.intent.requestId, jobRef: job.intent.jobRef, specRevision: job.intent.specRevision, state: h.state, phase: 'DYNAMIC_ACQUISITION', ocr: { capability: 'UNAVAILABLE', budgetState: 'NOT_CONFIGURED', processedPages: 0 }, requirementsState: 'DECLARED_NOT_EVALUATED', indexState: 'NOT_EVALUATED', coverage: { total: h.state === 'COMPLETE' ? h.queued : null, discovered: h.queued, acquired: h.acquired, registered: h.registered, pending: h.queued - h.cursor, gaps: h.gaps }, budget: { chargedBytes: h.chargedBytes, chargedMs: h.chargedMs, conservativeReservation: h.reservation !== null }, dynamic: { browserPages: h.browserPages, pagesQueued: h.pagesQueued, filesQueued: h.filesQueued, renderedStates: h.renderedStates, pdfExtracted: h.pdfExtracted, interactions: h.interactions }, finishedAt: h.finishedAt, nextEligibleAt: h.notBefore }); }
+export function tenantWebAttachmentInScope(spec, url, robots = false) { return tenantWebInScope({ url: spec.url, scope: { ...spec.scope, mode: 'SITE_SECTION' } }, url, { robots }); }
+/** Browser records refer to retained immutable evidence, never inline runtime bodies. */
+export const tenantWebBrowserResponseSchema = z.object({ url: tenantWebUrlSchema, finalUrl: tenantWebUrlSchema, status: z.number().int().min(200).max(299), headers: z.record(z.string(), z.string().max(8192)), ref: z.string().min(1).max(1024), hash: sha256Schema, observedAt: isoDateTimeSchema }).strict();
+export const tenantWebBrowserStateSchema = z.object({ schemaVersion: z.literal(1), ordinal: tenantWebDynamicTargetSchema.shape.ordinal, index: z.number().int().min(0).max(100), url: tenantWebUrlSchema, domRef: z.string().min(1).max(1024), domHash: sha256Schema, visibleRef: z.string().min(1).max(1024).optional(), visibleHash: sha256Schema.optional(), observedAt: isoDateTimeSchema, responseCount: z.number().int().min(0).max(64), navigationCount: z.number().int().min(0).max(64), actions: z.number().int().min(0).max(1000), done: z.boolean(), gap: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).nullable(), interactionRef: z.string().min(1).max(1024) }).strict();
+export function tenantWebPartIdentity(tenantId, parentRef, part) {
+    const parent = parseTenantResourceRef(parentRef);
+    if (!part || part.length > 256 || !parent || parent.storageKey !== tenantStorageKey(tenantId) || parent.resourceType !== 'evidence')
+        throw new Error('TENANT_WEB_PART_IDENTITY');
+    const resourceId = 'web_' + createHash('sha256').update(tenantWebCanonical(['TENANT_WEB_PART_V1', tenantId, parentRef, part])).digest('hex');
+    return { resourceId, version: 1, ...tenantResourceRefs({ tenantId, resourceType: 'evidence', resourceId, version: 1 }) };
+}
+export const tenantWebBrowserCapabilitySchema = z.object({ executablePath: z.string().min(1).max(4096).refine(s => s.startsWith('/') && !s.includes('\0')), navigationTimeoutMs: z.number().int().min(1000).max(30000).default(15000), settleMs: z.number().int().min(100).max(3000).default(300), maxRequests: z.number().int().min(1).max(64).default(32), captureVisible: z.boolean().optional() }).strict();

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

@@ -0,0 +1,41 @@
+/** 结果与覆盖独立于意图受理；仅有原件/字段出处才允许声明满足要求。 */
+import { z } from 'zod';
+import { isoDateTimeSchema, sha256Schema } from './common.js';
+import { tenantResourceRefSchema, parseTenantResourceRef } from './resource-scope.js';
+import { tenantWebJobRefSchema, tenantWebUrlSchema } from './tenant-web-collection.js';
+const count = z.number().int().nonnegative().safe();
+export const tenantWebFieldResultSchema = z.object({
+    name: z.string().min(1).max(64), state: z.enum(['PRESENT', 'MISSING', 'UNSUPPORTED']), value: z.json().nullable(),
+    citations: z.array(z.object({ evidenceRef: tenantResourceRefSchema, contentHash: sha256Schema, locator: z.string().min(1).max(2048), excerpt: z.string().min(1).max(4000) }).strict()).max(16),
+    reason: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).nullable(),
+}).strict().superRefine((v, ctx) => {
+    if (v.state === 'PRESENT' ? (v.value === null || v.citations.length === 0 || v.reason !== null) : (v.value !== null || v.reason === null))
+        ctx.addIssue({ code: 'custom', message: 'Present values require citations; gaps require a reason without an invented value' });
+    if (v.citations.some(c => parseTenantResourceRef(c.evidenceRef)?.resourceType !== 'evidence'))
+        ctx.addIssue({ code: 'custom', message: 'Citations require actual Evidence identities' });
+});
+export const tenantWebResultSchema = z.object({
+    schemaVersion: z.literal(1), jobRef: tenantWebJobRefSchema, evidenceRef: tenantResourceRefSchema,
+    sourceUrl: tenantWebUrlSchema, contentHash: sha256Schema, observedAt: isoDateTimeSchema,
+    documentRef: tenantResourceRefSchema.nullable(), fields: z.array(tenantWebFieldResultSchema).max(64),
+}).strict().superRefine((v, ctx) => {
+    const key = new URL(v.jobRef).hostname, mine = (ref) => parseTenantResourceRef(ref)?.storageKey === key;
+    if (!mine(v.evidenceRef) || parseTenantResourceRef(v.evidenceRef)?.resourceType !== 'evidence' || v.documentRef && (!mine(v.documentRef) || parseTenantResourceRef(v.documentRef)?.resourceType !== 'source_document') || v.fields.some(f => f.citations.some(c => !mine(c.evidenceRef))))
+        ctx.addIssue({ code: 'custom', message: 'Results and their typed evidence/document must retain the owning Tenant' });
+});
+export const tenantWebCoverageSchema = z.object({
+    schemaVersion: z.literal(1), jobRef: tenantWebJobRefSchema, scopeRevision: sha256Schema,
+    state: z.enum(['NOT_STARTED', 'PARTIAL', 'COMPLETE', 'UNKNOWN']), total: count.nullable(),
+    discovered: count, acquired: count, extracted: count, registered: count, pending: count,
+    frontierExhausted: z.boolean(), limitReached: z.boolean(),
+    gaps: z.array(z.object({ code: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/), url: tenantWebUrlSchema.nullable() }).strict()).max(100),
+}).strict().superRefine((v, ctx) => {
+    if (v.state === 'COMPLETE' && (!v.frontierExhausted || v.pending !== 0 || v.limitReached || v.gaps.length > 0))
+        ctx.addIssue({ code: 'custom', message: 'A truncated, pending or incomplete scope cannot be complete' });
+    if (v.state === 'COMPLETE' && (v.total !== v.discovered || v.acquired !== v.discovered || v.registered !== v.acquired))
+        ctx.addIssue({ code: 'custom', message: 'Completion requires a known exhausted target count and all originals registered' });
+    if (v.state === 'NOT_STARTED' && (v.discovered !== 0 || v.acquired !== 0 || v.extracted !== 0 || v.registered !== 0 || v.pending !== 0))
+        ctx.addIssue({ code: 'custom', message: 'Not-started coverage cannot carry completed work' });
+    if (v.acquired > v.discovered || v.extracted > v.acquired || v.registered > v.acquired || v.pending > v.discovered || v.total !== null && v.total < v.discovered)
+        ctx.addIssue({ code: 'custom', message: 'Coverage counters must describe actual bounded work' });
+});

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

@@ -0,0 +1,29 @@
+/** S5 operational state; acquisition/content evidence and business review remain separate. */
+import { z } from 'zod';
+import { tenantWebContentJobSchema } from './tenant-web-content.js';
+import { tenantWebJobRefSchema, tenantWebCanonical } from './tenant-web-collection.js';
+import { tenantCollectionCycleSchema } from './tenant-collection.js';
+import { isoDateTimeSchema } from './common.js';
+export const TENANT_WEB_WORKFLOW_CAPABILITY = 'TENANT_WEB_WORKFLOW_V1';
+export const tenantWebScheduleSchema = z.discriminatedUnion('mode', [z.object({ mode: z.literal('ONCE') }).strict(), z.object({ mode: z.literal('PERIODIC'), intervalSeconds: z.number().int().min(60).max(2592000) }).strict()]);
+export const tenantWebWorkflowJobSchema = z.object({ ...tenantWebContentJobSchema.shape, schemaVersion: z.literal(5), schedule: tenantWebScheduleSchema, cycle: z.object({ kind: z.enum(['INITIAL', 'MANUAL_REFRESH', 'DUE']), rootJobRef: tenantWebJobRefSchema, previousJobRef: tenantWebJobRefSchema.nullable(), ordinal: z.number().int().nonnegative().safe(), requestedEpoch: z.number().int().nonnegative().safe() }).strict() }).strict().superRefine((v, c) => {
+    const old = tenantWebContentJobSchema.safeParse({ schemaVersion: 4, intent: v.intent, policy: v.policy, contentPlan: v.contentPlan, contentRevision: v.contentRevision, retainedFrom: v.retainedFrom });
+    if (!old.success)
+        c.addIssue({ code: 'custom', message: 'Invalid frozen content intent' });
+    const wrongTenant = [v.cycle.rootJobRef, v.cycle.previousJobRef].some(ref => ref && new URL(ref).hostname !== new URL(v.intent.jobRef).hostname), wrongCycle = v.cycle.kind === 'INITIAL' ? (v.cycle.rootJobRef !== v.intent.jobRef || v.cycle.previousJobRef !== null || v.cycle.ordinal !== 0 || v.cycle.requestedEpoch !== 0) : (v.cycle.rootJobRef === v.intent.jobRef || v.cycle.previousJobRef === null || v.cycle.ordinal < 1 || v.retainedFrom !== null);
+    if (wrongTenant || wrongCycle)
+        c.addIssue({ code: 'custom', message: 'Cycle must retain its exact Tenant/root/previous identity' });
+    if (v.retainedFrom && v.schedule.mode !== 'ONCE')
+        c.addIssue({ code: 'custom', message: 'Retained derivation cannot enable periodic source observations' });
+});
+export function tenantWebExecutableContent(job) { return tenantWebContentJobSchema.parse({ schemaVersion: 4, intent: job.intent, policy: job.policy, contentPlan: job.contentPlan, contentRevision: job.contentRevision, retainedFrom: job.retainedFrom }); }
+export const tenantWebLifecycleSchema = z.object({ schemaVersion: z.literal(1), seq: z.number().int().nonnegative().safe(), epoch: z.number().int().nonnegative().safe(), state: z.enum(['ACTIVE', 'PAUSED', 'CANCELLED']), currentJobRef: tenantWebJobRefSchema, cycleOrdinal: z.number().int().nonnegative().safe(), lastObservedAt: isoDateTimeSchema.nullable(), updatedAt: isoDateTimeSchema }).strict().refine(v => v.epoch <= v.seq && v.cycleOrdinal <= v.seq);
+export const tenantWebControlInputSchema = z.object({ jobRef: tenantWebJobRefSchema, requestId: tenantCollectionCycleSchema, expectedEpoch: z.number().int().nonnegative().safe(), action: z.enum(['PAUSE', 'RESUME', 'CANCEL']) }).strict();
+export const tenantWebControlOperationSchema = z.object({ ...tenantWebControlInputSchema.shape, actor: tenantWebWorkflowJobSchema.shape.intent.shape.actor, authority: tenantWebWorkflowJobSchema.shape.intent.shape.authority }).strict();
+export const tenantWebLifecycleReceiptSchema = z.object({ operation: tenantWebControlOperationSchema, committed: tenantWebLifecycleSchema }).strict();
+export const tenantWebWorkflowStatusSchema = z.object({ jobRef: tenantWebJobRefSchema, requestId: tenantCollectionCycleSchema, rootJobRef: tenantWebJobRefSchema, executionJobRef: tenantWebJobRefSchema, state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL', 'PAUSED', 'CANCELLED']), control: tenantWebLifecycleSchema, cycle: tenantWebWorkflowJobSchema.shape.cycle, schedule: tenantWebScheduleSchema, nextDueAt: isoDateTimeSchema.nullable(), stages: z.object({ intent: z.literal('PERSISTED'), acquisition: z.object({ state: z.enum(['QUEUED', 'RUNNING', 'COMPLETE', 'PARTIAL']), discovered: z.number().int().nonnegative(), acquired: z.number().int().nonnegative(), registered: z.number().int().nonnegative(), pending: z.number().int().nonnegative(), gaps: z.array(z.string()).max(32) }).strict(), content: z.object({ state: z.enum(['PENDING', 'SATISFIED', 'PARTIAL']), processed: z.number().int().nonnegative(), registered: z.number().int().nonnegative(), gaps: z.array(z.string()).max(32) }).strict(), index: z.literal('NOT_PROVEN_QUERY_TENANT_INDEX_STATUS'), readability: z.literal('NOT_PROVEN_UNTIL_ACTUAL_READ'), review: z.literal('UNREVIEWED') }).strict(), budget: z.object({ chargedBytes: z.number().int().nonnegative(), chargedMs: z.number().int().nonnegative(), conservativeReservation: z.boolean() }).strict() }).strict().superRefine((v, c) => { const key = new URL(v.jobRef).hostname; if ([v.rootJobRef, v.executionJobRef, v.control.currentJobRef, v.cycle.rootJobRef].some(ref => new URL(ref).hostname !== key))
+    c.addIssue({ code: 'custom', message: 'Exact Tenant workflow required' }); });
+export function tenantWebNextDue(root, head, current) { if (root.schedule.mode !== 'PERIODIC' || head.state !== 'ACTIVE')
+    return null; return new Date(Math.max(Date.parse(head.lastObservedAt ?? current.intent.submittedAt), Date.parse(current.intent.submittedAt)) + root.schedule.intervalSeconds * 1000).toISOString(); }
+export const sameTenantWebWorkflow = (a, b) => tenantWebCanonical(a.intent.actor) === tenantWebCanonical(b.intent.actor) && tenantWebCanonical(a.intent.authority) === tenantWebCanonical(b.intent.authority) && tenantWebCanonical(a.policy) === tenantWebCanonical(b.policy) && a.intent.tenantId === b.intent.tenantId && a.intent.specRevision === b.intent.specRevision && a.contentRevision === b.contentRevision && tenantWebCanonical(a.schedule) === tenantWebCanonical(b.schedule);
+export const tenantWebLifecycleEventSchema = z.object({ before: tenantWebLifecycleSchema, after: tenantWebLifecycleSchema, operation: tenantWebControlOperationSchema.nullable() }).strict().refine(v => v.after.seq === v.before.seq + 1 && v.after.epoch === v.before.epoch + (v.operation ? 1 : 0) && (!v.before.lastObservedAt || v.after.lastObservedAt !== null && v.after.lastObservedAt >= v.before.lastObservedAt) && v.after.cycleOrdinal >= v.before.cycleOrdinal && v.after.cycleOrdinal <= v.before.cycleOrdinal + 1 && (v.operation !== null || v.after.state === v.before.state) && (!v.operation || v.operation.expectedEpoch === v.before.epoch && v.after.cycleOrdinal === v.before.cycleOrdinal && v.after.currentJobRef === v.before.currentJobRef && v.after.state === (v.operation.action === 'PAUSE' ? 'PAUSED' : v.operation.action === 'RESUME' ? 'ACTIVE' : 'CANCELLED')) && (v.before.state !== 'CANCELLED' || v.after.state === 'CANCELLED') && (v.after.cycleOrdinal !== v.before.cycleOrdinal ? v.before.state === 'ACTIVE' && v.after.state === 'ACTIVE' && v.after.currentJobRef !== v.before.currentJobRef : v.after.currentJobRef === v.before.currentJobRef));

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

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

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

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

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

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

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

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

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

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

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

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