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

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.d.ts

@@ -0,0 +1,263 @@
+/** Optional presentation extension. No new execution authority or automatic actions. */
+import { z } from 'zod';
+export declare const agentGuidanceHeader = "x-knowledge-agent-guidance", agentGuidanceFeature = "task-guidance-v1", agentResupplyGuidanceFeature = "task-guidance-v2";
+export declare const agentGuidanceActionSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    tool: z.ZodEnum<{
+        knowledge_discover: "knowledge_discover";
+        knowledge_execute: "knowledge_execute";
+    }>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    canExecute: z.ZodBoolean;
+    automatic: z.ZodLiteral<false>;
+    missingFields: z.ZodArray<z.ZodString>;
+    reasonCode: z.ZodString;
+}, z.core.$strict>;
+export declare const agentInputHintSchema: z.ZodObject<{
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+        MISSING: "MISSING";
+        INVALID: "INVALID";
+        UNSUPPORTED: "UNSUPPORTED";
+        CONFLICT: "CONFLICT";
+    }>;
+    expected: z.ZodString;
+    prompt: z.ZodString;
+    source: z.ZodEnum<{
+        USER_INPUT: "USER_INPUT";
+        CURRENT_STATE: "CURRENT_STATE";
+        PRIOR_RESULT: "PRIOR_RESULT";
+        INDEPENDENT_REVIEW: "INDEPENDENT_REVIEW";
+    }>;
+    choices: z.ZodArray<z.ZodJSONSchema>;
+    constraints: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strict>;
+export declare const agentTaskContextSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    jobRef: z.ZodOptional<z.ZodString>;
+    projectRef: z.ZodOptional<z.ZodString>;
+    projectKey: z.ZodOptional<z.ZodString>;
+    sourceId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+    recipientTenantId: z.ZodOptional<z.ZodString>;
+    sourceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    spec: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    extraction: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    citation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export declare const agentTaskInputSchema: z.ZodObject<{
+    goal: z.ZodString;
+    context: z.ZodDefault<z.ZodObject<{
+        query: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        jobRef: z.ZodOptional<z.ZodString>;
+        projectRef: z.ZodOptional<z.ZodString>;
+        projectKey: z.ZodOptional<z.ZodString>;
+        sourceId: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+        recipientTenantId: z.ZodOptional<z.ZodString>;
+        sourceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        spec: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        extraction: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        citation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+}, z.core.$strict>;
+export type AgentTaskInput = z.input<typeof agentTaskInputSchema>;
+export declare const agentTaskPlanSchema: z.ZodObject<{
+    template: z.ZodEnum<{
+        RESEARCH_EXISTING: "RESEARCH_EXISTING";
+        COLLECT_WEBSITE: "COLLECT_WEBSITE";
+        INSPECT_COLLECTION: "INSPECT_COLLECTION";
+        VERIFY_CITATION: "VERIFY_CITATION";
+        PROJECT_RESEARCH: "PROJECT_RESEARCH";
+        SHARE_MATERIAL: "SHARE_MATERIAL";
+        GOVERNANCE: "GOVERNANCE";
+        UNRECOGNIZED: "UNRECOGNIZED";
+    }>;
+    status: z.ZodLiteral<"SUGGESTED_NOT_EXECUTED">;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        dependsOn: z.ZodArray<z.ZodString>;
+        capability: z.ZodNullable<z.ZodString>;
+        state: z.ZodEnum<{
+            READY: "READY";
+            NOT_AUTHORIZED: "NOT_AUTHORIZED";
+            NEEDS_INPUT: "NEEDS_INPUT";
+            NEEDS_PRIOR_RESULT: "NEEDS_PRIOR_RESULT";
+        }>;
+        action: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            tool: z.ZodEnum<{
+                knowledge_discover: "knowledge_discover";
+                knowledge_execute: "knowledge_execute";
+            }>;
+            arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            canExecute: z.ZodBoolean;
+            automatic: z.ZodLiteral<false>;
+            missingFields: z.ZodArray<z.ZodString>;
+            reasonCode: z.ZodString;
+        }, z.core.$strict>>;
+        inputHints: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodEnum<{
+                MISSING: "MISSING";
+                INVALID: "INVALID";
+                UNSUPPORTED: "UNSUPPORTED";
+                CONFLICT: "CONFLICT";
+            }>;
+            expected: z.ZodString;
+            prompt: z.ZodString;
+            source: z.ZodEnum<{
+                USER_INPUT: "USER_INPUT";
+                CURRENT_STATE: "CURRENT_STATE";
+                PRIOR_RESULT: "PRIOR_RESULT";
+                INDEPENDENT_REVIEW: "INDEPENDENT_REVIEW";
+            }>;
+            choices: z.ZodArray<z.ZodJSONSchema>;
+            constraints: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    guidance: z.ZodString;
+}, z.core.$strict>;
+export declare const agentRecoverySchema: z.ZodObject<{
+    reasonCode: z.ZodEnum<{
+        INPUT_REQUIRED: "INPUT_REQUIRED";
+        CURSOR_RESTART_REQUIRED: "CURSOR_RESTART_REQUIRED";
+        STATE_CHANGED: "STATE_CHANGED";
+        INSPECT_PERSISTED_RESULT: "INSPECT_PERSISTED_RESULT";
+        SEMANTIC_PLAN_REQUIRED: "SEMANTIC_PLAN_REQUIRED";
+        AUTHORITY_REQUIRED: "AUTHORITY_REQUIRED";
+        ACCESS_BLOCKED: "ACCESS_BLOCKED";
+        OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
+        INSPECT_INPUT: "INSPECT_INPUT";
+    }>;
+    summary: z.ZodString;
+    inputHints: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            MISSING: "MISSING";
+            INVALID: "INVALID";
+            UNSUPPORTED: "UNSUPPORTED";
+            CONFLICT: "CONFLICT";
+        }>;
+        expected: z.ZodString;
+        prompt: z.ZodString;
+        source: z.ZodEnum<{
+            USER_INPUT: "USER_INPUT";
+            CURRENT_STATE: "CURRENT_STATE";
+            PRIOR_RESULT: "PRIOR_RESULT";
+            INDEPENDENT_REVIEW: "INDEPENDENT_REVIEW";
+        }>;
+        choices: z.ZodArray<z.ZodJSONSchema>;
+        constraints: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    }, z.core.$strict>>;
+    nextActions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        tool: z.ZodEnum<{
+            knowledge_discover: "knowledge_discover";
+            knowledge_execute: "knowledge_execute";
+        }>;
+        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        canExecute: z.ZodBoolean;
+        automatic: z.ZodLiteral<false>;
+        missingFields: z.ZodArray<z.ZodString>;
+        reasonCode: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentRecovery = z.infer<typeof agentRecoverySchema>;
+export declare const agentGuidedFailureSchema: z.ZodObject<{
+    ref: z.ZodOptional<z.ZodString>;
+    completedPhase: z.ZodOptional<z.ZodEnum<{
+        REGISTERED: "REGISTERED";
+        ROUTE_COMMITTED: "ROUTE_COMMITTED";
+        CURRENTNESS_NOTIFIED: "CURRENTNESS_NOTIFIED";
+        SOURCE_REGISTERED: "SOURCE_REGISTERED";
+        BATCH_PERSISTED: "BATCH_PERSISTED";
+        VALIDATED: "VALIDATED";
+        PERSISTED: "PERSISTED";
+        CATALOG_PROJECTED: "CATALOG_PROJECTED";
+        DECLARATION_PERSISTED: "DECLARATION_PERSISTED";
+        CURRENTNESS_RECORDED: "CURRENTNESS_RECORDED";
+        SOURCE_PERSISTED: "SOURCE_PERSISTED";
+        REQUEST_PERSISTED: "REQUEST_PERSISTED";
+        PROJECT_CONTROL_COMMITTED: "PROJECT_CONTROL_COMMITTED";
+        WEB_INTENT_PERSISTED: "WEB_INTENT_PERSISTED";
+        WEB_CONTROL_COMMITTED: "WEB_CONTROL_COMMITTED";
+    }>>;
+    errorCode: z.ZodEnum<{
+        TENANT_MANAGEMENT_INVALID_INPUT: "TENANT_MANAGEMENT_INVALID_INPUT";
+        TENANT_MANAGEMENT_FORBIDDEN: "TENANT_MANAGEMENT_FORBIDDEN";
+        TENANT_MANAGEMENT_AUTHORITY_CHANGED: "TENANT_MANAGEMENT_AUTHORITY_CHANGED";
+        TENANT_MANAGEMENT_RUNTIME_OWNER_REQUIRED: "TENANT_MANAGEMENT_RUNTIME_OWNER_REQUIRED";
+        TENANT_MANAGEMENT_IDEMPOTENCY_CONFLICT: "TENANT_MANAGEMENT_IDEMPOTENCY_CONFLICT";
+        TENANT_MANAGEMENT_VERSION_CONFLICT: "TENANT_MANAGEMENT_VERSION_CONFLICT";
+        TENANT_MANAGEMENT_SOURCE_FORBIDDEN: "TENANT_MANAGEMENT_SOURCE_FORBIDDEN";
+        TENANT_MANAGEMENT_REVIEW_REQUIRED: "TENANT_MANAGEMENT_REVIEW_REQUIRED";
+        TENANT_MANAGEMENT_POLICY_BLOCKED: "TENANT_MANAGEMENT_POLICY_BLOCKED";
+        TENANT_MANAGEMENT_UNAVAILABLE: "TENANT_MANAGEMENT_UNAVAILABLE";
+        TENANT_MANAGEMENT_INCOMPLETE: "TENANT_MANAGEMENT_INCOMPLETE";
+        TENANT_MANAGEMENT_INPUT_BUDGET: "TENANT_MANAGEMENT_INPUT_BUDGET";
+        TENANT_MANAGEMENT_NOT_FOUND: "TENANT_MANAGEMENT_NOT_FOUND";
+        TENANT_WEB_SEMANTIC_COMPILER_UNAVAILABLE: "TENANT_WEB_SEMANTIC_COMPILER_UNAVAILABLE";
+        TENANT_WEB_CONTENT_FIELD_PLAN_REQUIRED: "TENANT_WEB_CONTENT_FIELD_PLAN_REQUIRED";
+        TENANT_WEB_RETAINED_SCOPE_FORBIDDEN: "TENANT_WEB_RETAINED_SCOPE_FORBIDDEN";
+        TENANT_WEB_RESULT_NOT_FOUND: "TENANT_WEB_RESULT_NOT_FOUND";
+        TENANT_WEB_CONTROL_CONFLICT: "TENANT_WEB_CONTROL_CONFLICT";
+        TENANT_WEB_CANCELLED: "TENANT_WEB_CANCELLED";
+        TENANT_WEB_PAUSED: "TENANT_WEB_PAUSED";
+        TENANT_WEB_CYCLE_PENDING: "TENANT_WEB_CYCLE_PENDING";
+        TENANT_WEB_RUNTIME_OR_DELEGATION_UNAVAILABLE: "TENANT_WEB_RUNTIME_OR_DELEGATION_UNAVAILABLE";
+    }>;
+    guidance: z.ZodObject<{
+        reasonCode: z.ZodEnum<{
+            INPUT_REQUIRED: "INPUT_REQUIRED";
+            CURSOR_RESTART_REQUIRED: "CURSOR_RESTART_REQUIRED";
+            STATE_CHANGED: "STATE_CHANGED";
+            INSPECT_PERSISTED_RESULT: "INSPECT_PERSISTED_RESULT";
+            SEMANTIC_PLAN_REQUIRED: "SEMANTIC_PLAN_REQUIRED";
+            AUTHORITY_REQUIRED: "AUTHORITY_REQUIRED";
+            ACCESS_BLOCKED: "ACCESS_BLOCKED";
+            OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
+            INSPECT_INPUT: "INSPECT_INPUT";
+        }>;
+        summary: z.ZodString;
+        inputHints: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodEnum<{
+                MISSING: "MISSING";
+                INVALID: "INVALID";
+                UNSUPPORTED: "UNSUPPORTED";
+                CONFLICT: "CONFLICT";
+            }>;
+            expected: z.ZodString;
+            prompt: z.ZodString;
+            source: z.ZodEnum<{
+                USER_INPUT: "USER_INPUT";
+                CURRENT_STATE: "CURRENT_STATE";
+                PRIOR_RESULT: "PRIOR_RESULT";
+                INDEPENDENT_REVIEW: "INDEPENDENT_REVIEW";
+            }>;
+            choices: z.ZodArray<z.ZodJSONSchema>;
+            constraints: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        }, z.core.$strict>>;
+        nextActions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            tool: z.ZodEnum<{
+                knowledge_discover: "knowledge_discover";
+                knowledge_execute: "knowledge_execute";
+            }>;
+            arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            canExecute: z.ZodBoolean;
+            automatic: z.ZodLiteral<false>;
+            missingFields: z.ZodArray<z.ZodString>;
+            reasonCode: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$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.d.ts

@@ -0,0 +1,24 @@
+/** Derive bounded hints from the actual capability schema, never from raw validator messages. */
+import { type AgentCapabilityName } from './agent-entry.js';
+export declare function agentInputHints(name: AgentCapabilityName, raw: unknown): {
+    path: string;
+    kind: "MISSING" | "INVALID" | "UNSUPPORTED" | "CONFLICT";
+    expected: string;
+    prompt: string;
+    source: "USER_INPUT" | "CURRENT_STATE" | "PRIOR_RESULT" | "INDEPENDENT_REVIEW";
+    choices: import("zod").JSONType[];
+    constraints: Record<string, import("zod").JSONType>;
+}[];
+export declare function agentResumeArguments(name: AgentCapabilityName, raw: unknown): Record<string, unknown>;
+/** Explain invalid supplied fields and any payload fields intentionally omitted from suggestions. */
+export declare function agentCompletionHints(name: AgentCapabilityName, raw: unknown, resupplyFields?: readonly string[]): {
+    path: string;
+    kind: "MISSING" | "INVALID" | "UNSUPPORTED" | "CONFLICT";
+    expected: string;
+    prompt: string;
+    source: "USER_INPUT" | "CURRENT_STATE" | "PRIOR_RESULT" | "INDEPENDENT_REVIEW";
+    choices: import("zod").JSONType[];
+    constraints: Record<string, import("zod").JSONType>;
+}[];
+/** Carry only declared field names, never omitted values, across inspection hops. */
+export declare function agentResupplyFields(name: AgentCapabilityName, raw: unknown): string[];

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); }