@cats-inc/cats-platform 0.1.0

package/build/server/platform/orchestration/providerAgentDecision.js

@@ -0,0 +1,814 @@
+import { ADDRESSABLE_TARGET_KIND_VALUES, SUPERVISION_APPROVAL_THRESHOLD_VALUES, SUPERVISION_AUTONOMY_VALUES, SUPERVISION_CHECKPOINT_CADENCE_VALUES, SUPERVISED_TOOL_APPROVAL_VALUES, SUPERVISED_TOOL_BLOCKING_VALUES, SUPERVISED_TOOL_CANCELLATION_VALUES, SUPERVISED_TOOL_EVIDENCE_VALUES, SUPERVISED_TOOL_PREFLIGHT_VALUES, SUPERVISED_TOOL_SIDE_EFFECT_VALUES, SUPERVISION_FALLBACK_POLICY_VALUES, SUPERVISION_SCAFFOLDING_VALUES, SUPERVISION_TASK_GRANULARITY_VALUES, SUPERVISION_TOOL_SCOPE_VALUES, SUPERVISION_VALIDATION_VALUES, } from '../supervision/contracts.js';
+export const PROVIDER_AGENT_DECISION_CONTRACT_VERSION = 1;
+export const PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH = 280;
+export const PROVIDER_AGENT_MAX_SUMMARIES = 24;
+export const PROVIDER_AGENT_MAX_SUMMARY_KEY_LENGTH = 80;
+export const PROVIDER_AGENT_MAX_GOAL_LENGTH = 2000;
+export const PROVIDER_AGENT_MAX_CONTEXT_REFS = 64;
+export const PROVIDER_AGENT_MAX_CONTEXT_REF_LENGTH = 240;
+export const PROVIDER_AGENT_MAX_INVARIANTS = 24;
+export const PROVIDER_AGENT_MAX_INVARIANT_LENGTH = 320;
+export const PROVIDER_AGENT_MAX_TOOL_REASON_LENGTH = 280;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_HINTS = 8;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_HINT_LENGTH = 400;
+export const PROVIDER_AGENT_MAX_TOOL_NAME_LENGTH = 160;
+export const PROVIDER_AGENT_MAX_TOOL_DESCRIPTION_LENGTH = 500;
+export const PROVIDER_AGENT_MAX_TOOL_MANIFEST_VERSION_LENGTH = 40;
+export const PROVIDER_AGENT_MAX_TOOL_FAILURE_CODES = 16;
+export const PROVIDER_AGENT_MAX_TOOL_FAILURE_CODE_LENGTH = 80;
+export const PROVIDER_AGENT_MAX_SEMANTIC_PLAN_STEPS = 12;
+export const PROVIDER_AGENT_MAX_STEP_DEPENDENCIES = 8;
+export const PROVIDER_AGENT_MAX_STEP_DEPENDENCY_LENGTH = 80;
+export const PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH = 120;
+export const PROVIDER_AGENT_MAX_SCHEMA_REF_ID_LENGTH = 160;
+export const PROVIDER_AGENT_MAX_SCHEMA_REF_VERSION_LENGTH = 40;
+export const PROVIDER_AGENT_MAX_SCHEMA_REF_URI_LENGTH = 1000;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_DEPTH = 6;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_OBJECT_KEYS = 32;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_ARRAY_ITEMS = 32;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_KEY_LENGTH = 80;
+export const PROVIDER_AGENT_MAX_TOOL_INPUT_STRING_LENGTH = 4000;
+export const PROVIDER_AGENT_DECISION_CONFIDENCE_VALUES = ['low', 'medium', 'high'];
+export const PROVIDER_AGENT_TASK_RISK_VALUES = ['low', 'medium', 'high'];
+export const PROVIDER_AGENT_TASK_KIND_VALUES = [
+    'chat_turn',
+    'work_run',
+    'code_task',
+    'code_relay',
+];
+export const PROVIDER_AGENT_SUMMARY_KIND_VALUES = [
+    'count',
+    'ratio',
+    'enumerated_outcome',
+    'opaque_ref',
+];
+export const PROVIDER_AGENT_DECISION_KIND_VALUES = [
+    'semantic_plan',
+    'tool_request',
+    'delegation_request',
+    'recovery_decision',
+];
+export const PROVIDER_AGENT_SEMANTIC_PLAN_STEP_ACTION_VALUES = [
+    'call_tool',
+    'delegate_run',
+    'request_approval',
+    'respond',
+];
+export const PROVIDER_AGENT_DELEGATION_BLOCKING_VALUES = ['blocking', 'async'];
+export const PROVIDER_AGENT_TARGET_PROJECTION_VALUES = ['chat', 'work', 'code'];
+const PROVIDER_AGENT_SEMANTIC_PLAN_DECISION_FIELDS = [
+    'contractVersion',
+    'kind',
+    'decisionId',
+    'planId',
+    'confidence',
+    'rationaleSummary',
+    'steps',
+];
+const PROVIDER_AGENT_TOOL_REQUEST_DECISION_FIELDS = [
+    'contractVersion',
+    'kind',
+    'decisionId',
+    'confidence',
+    'toolName',
+    'target',
+    'input',
+    'expectedOutputSchemaRef',
+    'rationaleSummary',
+];
+const PROVIDER_AGENT_DELEGATION_REQUEST_DECISION_FIELDS = [
+    'contractVersion',
+    'kind',
+    'decisionId',
+    'confidence',
+    'target',
+    'goalSummary',
+    'blocking',
+    'budget',
+    'rationaleSummary',
+];
+const PROVIDER_AGENT_RECOVERY_DECISION_FIELDS = [
+    'contractVersion',
+    'kind',
+    'decisionId',
+    'confidence',
+    'rejectedActionId',
+    'selectedFallback',
+    'correctedInput',
+    'rationaleSummary',
+];
+const PROVIDER_AGENT_SEMANTIC_PLAN_STEP_FIELDS = [
+    'stepId',
+    'summary',
+    'action',
+    'toolName',
+    'target',
+    'input',
+    'expectedOutputSchemaRef',
+    'dependsOn',
+];
+const PROVIDER_AGENT_SCHEMA_REF_FIELDS = ['id', 'version', 'format', 'uri'];
+const PROVIDER_AGENT_BUDGET_FIELDS = [
+    'maxCostUsd',
+    'maxTokens',
+    'maxDurationMs',
+    'hardStop',
+];
+const PROVIDER_AGENT_DURABLE_AGENT_TARGET_FIELDS = [
+    'kind',
+    'agentId',
+    'projection',
+];
+const PROVIDER_AGENT_EXECUTION_TARGET_FIELDS = [
+    'kind',
+    'provider',
+    'model',
+    'control',
+];
+const PROVIDER_AGENT_TEMPORARY_PARTICIPANT_TARGET_FIELDS = [
+    'kind',
+    'participantId',
+    'roleHint',
+    'displayName',
+    'avatarHint',
+];
+const PROVIDER_AGENT_WORKER_TOOL_TARGET_FIELDS = [
+    'kind',
+    'toolName',
+    'workerProfileId',
+];
+const PROVIDER_AGENT_TOOL_DESCRIPTOR_FIELDS = ['manifest', 'reason', 'inputHints'];
+const PROVIDER_AGENT_TOOL_MANIFEST_FIELDS = [
+    'schemaVersion',
+    'name',
+    'manifestVersion',
+    'description',
+    'sideEffect',
+    'preflight',
+    'blocking',
+    'cancellation',
+    'approval',
+    'evidence',
+    'failureCodes',
+    'maxBudgetHint',
+    'inputSchema',
+    'outputSchema',
+];
+const PROVIDER_AGENT_OBSERVATION_SUMMARY_FIELDS = [
+    'key',
+    'kind',
+    'value',
+    'sourceRef',
+];
+const PROVIDER_AGENT_OBSERVATION_POLICY_FIELDS = [
+    'snapshotRef',
+    'dials',
+    'parentToolScope',
+    'allowedFallbacks',
+];
+const PROVIDER_AGENT_SUPERVISION_POLICY_FIELDS = [
+    'autonomy',
+    'taskGranularity',
+    'toolScope',
+    'scaffolding',
+    'validation',
+    'checkpointCadence',
+    'approvalThreshold',
+    'fallbackPolicy',
+];
+export function validateProviderAgentBoundedObservation(observation) {
+    const errors = [];
+    validateRequiredString(errors, 'observationId', observation.observationId);
+    validateRequiredString(errors, 'runId', observation.runId);
+    validateBoundedString(errors, 'goal', observation.goal, PROVIDER_AGENT_MAX_GOAL_LENGTH);
+    if (!isRecord(observation.task)) {
+        errors.push('task must be an object');
+    }
+    else {
+        validateEnumValue(errors, 'task.kind', observation.task.kind, PROVIDER_AGENT_TASK_KIND_VALUES);
+        validateEnumValue(errors, 'task.risk', observation.task.risk, PROVIDER_AGENT_TASK_RISK_VALUES);
+    }
+    if (!isRecord(observation.actor)) {
+        errors.push('actor must be an object');
+    }
+    else {
+        validateRequiredString(errors, 'actor.actorRef', observation.actor.actorRef);
+        validateRequiredString(errors, 'actor.capabilityProfileRef', observation.actor.capabilityProfileRef);
+        validateAddressableTarget(errors, 'actor.target', observation.actor.target);
+    }
+    validateObservationPolicy(errors, observation.policy);
+    validateBudgetEnvelope(errors, observation.budget);
+    if (observation.contractVersion !== PROVIDER_AGENT_DECISION_CONTRACT_VERSION) {
+        errors.push(`contractVersion must be ${PROVIDER_AGENT_DECISION_CONTRACT_VERSION}`);
+    }
+    if (!Array.isArray(observation.availableTools)) {
+        errors.push('availableTools must be an array');
+    }
+    else {
+        const manifestNames = observation.availableTools
+            .map((tool) => readToolDescriptorManifestName(tool))
+            .filter((name) => name !== null);
+        if (new Set(manifestNames).size !== manifestNames.length) {
+            errors.push('availableTools must not contain duplicate manifest names');
+        }
+        observation.availableTools.forEach((tool, index) => {
+            validateToolDescriptor(errors, tool, index);
+        });
+    }
+    validateBoundedStringArray(errors, 'contextRefs', observation.contextRefs, PROVIDER_AGENT_MAX_CONTEXT_REFS, PROVIDER_AGENT_MAX_CONTEXT_REF_LENGTH);
+    validateBoundedStringArray(errors, 'invariants', observation.invariants, PROVIDER_AGENT_MAX_INVARIANTS, PROVIDER_AGENT_MAX_INVARIANT_LENGTH);
+    if (!Array.isArray(observation.summaries)) {
+        errors.push('summaries must be an array');
+    }
+    else {
+        if (observation.summaries.length > PROVIDER_AGENT_MAX_SUMMARIES) {
+            errors.push(`summaries must contain ${PROVIDER_AGENT_MAX_SUMMARIES} entries or fewer`);
+        }
+        observation.summaries.forEach((summary, index) => {
+            validateObservationSummary(errors, summary, index);
+        });
+    }
+    return errors;
+}
+function validateObservationPolicy(errors, policy) {
+    if (!isRecord(policy)) {
+        errors.push('policy must be an object');
+        return;
+    }
+    validateAllowedRecordFields(errors, 'policy', policy, PROVIDER_AGENT_OBSERVATION_POLICY_FIELDS);
+    validateOptionalEnumValue(errors, 'policy.parentToolScope', policy.parentToolScope, SUPERVISION_TOOL_SCOPE_VALUES);
+    if (!isRecord(policy.dials)) {
+        errors.push('policy.dials must be an object');
+        return;
+    }
+    validateSupervisionPolicy(errors, policy.dials);
+    validateAllowedFallbacks(errors, policy.allowedFallbacks, policy.dials.fallbackPolicy);
+}
+export function validateProviderAgentDecision(input) {
+    const errors = validateProviderAgentBoundedObservation(input.observation);
+    const availableTools = Array.isArray(input.observation.availableTools)
+        ? input.observation.availableTools
+            .filter((tool) => isRecord(tool)
+            && isRecord(tool.manifest)
+            && typeof tool.manifest.name === 'string')
+        : [];
+    const availableToolNames = new Set(availableTools.map((tool) => tool.manifest.name));
+    const availableToolByName = new Map(availableTools.map((tool) => [tool.manifest.name, tool.manifest]));
+    validateBoundedString(errors, 'decisionId', input.decision.decisionId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+    validateEnumValue(errors, 'decision.kind', input.decision.kind, PROVIDER_AGENT_DECISION_KIND_VALUES);
+    validateEnumValue(errors, 'decision.confidence', input.decision.confidence, PROVIDER_AGENT_DECISION_CONFIDENCE_VALUES);
+    if (input.decision.contractVersion !== PROVIDER_AGENT_DECISION_CONTRACT_VERSION) {
+        errors.push(`decision contractVersion must be ${PROVIDER_AGENT_DECISION_CONTRACT_VERSION}`);
+    }
+    if (isRecord(input.decision)) {
+        validateDecisionAllowedFields(errors, input.decision);
+    }
+    switch (input.decision.kind) {
+        case 'semantic_plan':
+            validateSemanticPlanDecision(errors, input.decision, availableToolNames, availableToolByName);
+            break;
+        case 'tool_request':
+            validateToolRequestDecision(errors, input.decision, availableToolNames, availableToolByName);
+            break;
+        case 'delegation_request':
+            validateDelegationTarget(errors, input.decision);
+            validateBoundedString(errors, 'goalSummary', input.decision.goalSummary, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+            validateBoundedString(errors, 'rationaleSummary', input.decision.rationaleSummary, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+            validateEnumValue(errors, 'delegation_request.blocking', input.decision.blocking, PROVIDER_AGENT_DELEGATION_BLOCKING_VALUES);
+            validateBudgetEnvelope(errors, input.decision.budget, 'delegation_request.budget');
+            break;
+        case 'recovery_decision':
+            validateRecoveryDecision(errors, input.observation, input.decision);
+            break;
+        default:
+            return errors;
+    }
+    return errors;
+}
+function validateSemanticPlanDecision(errors, decision, availableToolNames, availableToolByName) {
+    validateBoundedString(errors, 'planId', decision.planId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+    validateBoundedString(errors, 'rationaleSummary', decision.rationaleSummary, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+    if (!Array.isArray(decision.steps)) {
+        errors.push('semantic_plan.steps must be an array');
+        return;
+    }
+    if (decision.steps.length === 0) {
+        errors.push('semantic_plan.steps must not be empty');
+    }
+    if (decision.steps.length > PROVIDER_AGENT_MAX_SEMANTIC_PLAN_STEPS) {
+        errors.push(`semantic_plan.steps must contain ${PROVIDER_AGENT_MAX_SEMANTIC_PLAN_STEPS} entries or fewer`);
+    }
+    const stepRecords = decision.steps.filter((step, index) => {
+        if (!isRecord(step)) {
+            errors.push(`semantic_plan.steps[${index}] must be an object`);
+            return false;
+        }
+        return true;
+    });
+    const validStepIds = stepRecords
+        .map((step) => step.stepId)
+        .filter((stepId) => typeof stepId === 'string' && stepId.trim() !== '');
+    if (new Set(validStepIds).size !== validStepIds.length) {
+        errors.push('semantic_plan.steps must have unique stepId values');
+    }
+    const stepIds = new Set(validStepIds);
+    for (const step of stepRecords) {
+        validateAllowedRecordFields(errors, `step ${step.stepId}`, step, PROVIDER_AGENT_SEMANTIC_PLAN_STEP_FIELDS);
+        validateBoundedString(errors, 'step.stepId', step.stepId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+        validateEnumValue(errors, `step ${step.stepId}.action`, step.action, PROVIDER_AGENT_SEMANTIC_PLAN_STEP_ACTION_VALUES);
+        validateBoundedString(errors, `step ${step.stepId} summary`, step.summary, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+        if (step.input !== undefined) {
+            validateBoundedToolInputObject(errors, `step ${step.stepId}.input`, step.input, false);
+        }
+        validateSemanticPlanStepTarget(errors, step);
+        if (step.action === 'call_tool') {
+            validateToolName(errors, step.toolName, availableToolNames, `step ${step.stepId}`);
+            validateExpectedOutputSchemaRef(errors, `step ${step.stepId}`, step.expectedOutputSchemaRef, step.toolName ? availableToolByName.get(step.toolName) : undefined);
+        }
+        if (step.dependsOn !== undefined) {
+            if (!Array.isArray(step.dependsOn)) {
+                errors.push(`step ${step.stepId}.dependsOn must be an array`);
+            }
+            else {
+                const dependencyShapeErrorCount = errors.length;
+                validateBoundedStringArray(errors, `step ${step.stepId}.dependsOn`, step.dependsOn, PROVIDER_AGENT_MAX_STEP_DEPENDENCIES, PROVIDER_AGENT_MAX_STEP_DEPENDENCY_LENGTH);
+                if (errors.length === dependencyShapeErrorCount) {
+                    validateStepDependencies(errors, step, stepIds);
+                }
+            }
+        }
+    }
+}
+function validateDecisionAllowedFields(errors, decision) {
+    switch (decision.kind) {
+        case 'semantic_plan':
+            validateAllowedRecordFields(errors, 'semantic_plan', decision, PROVIDER_AGENT_SEMANTIC_PLAN_DECISION_FIELDS);
+            break;
+        case 'tool_request':
+            validateAllowedRecordFields(errors, 'tool_request', decision, PROVIDER_AGENT_TOOL_REQUEST_DECISION_FIELDS);
+            break;
+        case 'delegation_request':
+            validateAllowedRecordFields(errors, 'delegation_request', decision, PROVIDER_AGENT_DELEGATION_REQUEST_DECISION_FIELDS);
+            break;
+        case 'recovery_decision':
+            validateAllowedRecordFields(errors, 'recovery_decision', decision, PROVIDER_AGENT_RECOVERY_DECISION_FIELDS);
+            break;
+        default:
+            return;
+    }
+}
+function validateSemanticPlanStepTarget(errors, step) {
+    if (step.target === undefined) {
+        return;
+    }
+    const target = validateAddressableTarget(errors, `step ${step.stepId}.target`, step.target);
+    if (!target) {
+        return;
+    }
+    if (step.action === 'call_tool') {
+        if (target.kind !== 'worker_tool') {
+            errors.push(`step ${step.stepId}.target.kind must be worker_tool for call_tool`);
+            return;
+        }
+        if (target.toolName !== step.toolName) {
+            errors.push(`step ${step.stepId}.target.toolName must match step toolName ${step.toolName}`);
+        }
+        return;
+    }
+    if (target.kind === 'worker_tool') {
+        errors.push(`step ${step.stepId}.target.kind must not be worker_tool unless action is call_tool`);
+    }
+}
+function validateAllowedRecordFields(errors, field, value, allowedFields) {
+    const allowed = new Set(allowedFields);
+    const unsupportedFields = Object.keys(value)
+        .filter((key) => !allowed.has(key))
+        .sort();
+    if (unsupportedFields.length > 0) {
+        errors.push(`${field} contains unsupported fields: ${unsupportedFields.join(', ')}`);
+    }
+}
+function validateToolRequestDecision(errors, decision, availableToolNames, availableToolByName) {
+    validateToolName(errors, decision.toolName, availableToolNames, 'tool_request');
+    validateToolRequestTarget(errors, decision);
+    validateExpectedOutputSchemaRef(errors, 'tool_request', decision.expectedOutputSchemaRef, availableToolByName.get(decision.toolName));
+    validateBoundedToolInputObject(errors, 'tool_request.input', decision.input, true);
+    validateBoundedString(errors, 'rationaleSummary', decision.rationaleSummary, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+}
+function validateExpectedOutputSchemaRef(errors, field, schemaRef, manifest) {
+    if (schemaRef === undefined || schemaRef === null) {
+        return;
+    }
+    if (!validateSchemaRef(errors, `${field}.expectedOutputSchemaRef`, schemaRef)) {
+        return;
+    }
+    if (!manifest) {
+        return;
+    }
+    if (schemaRef.id !== manifest.outputSchema.id
+        || schemaRef.version !== manifest.outputSchema.version
+        || schemaRef.format !== manifest.outputSchema.format) {
+        errors.push(`${field}.expectedOutputSchemaRef must match ${manifest.name} outputSchema`);
+    }
+}
+function validateSchemaRef(errors, field, value) {
+    if (!isRecord(value)) {
+        errors.push(`${field} must be an object`);
+        return false;
+    }
+    validateAllowedRecordFields(errors, field, value, PROVIDER_AGENT_SCHEMA_REF_FIELDS);
+    const previousErrorCount = errors.length;
+    validateBoundedString(errors, `${field}.id`, value.id, PROVIDER_AGENT_MAX_SCHEMA_REF_ID_LENGTH);
+    validateBoundedString(errors, `${field}.version`, value.version, PROVIDER_AGENT_MAX_SCHEMA_REF_VERSION_LENGTH);
+    validateEnumValue(errors, `${field}.format`, value.format, ['json_schema']);
+    validateOptionalBoundedString(errors, `${field}.uri`, value.uri, PROVIDER_AGENT_MAX_SCHEMA_REF_URI_LENGTH);
+    return errors.length === previousErrorCount;
+}
+function validateToolRequestTarget(errors, decision) {
+    const target = validateAddressableTarget(errors, 'tool_request.target', decision.target);
+    if (!target) {
+        return;
+    }
+    if (target.kind !== 'worker_tool') {
+        errors.push('tool_request.target.kind must be worker_tool');
+        return;
+    }
+    if (target.toolName !== decision.toolName) {
+        errors.push(`tool_request.target.toolName must match tool_request.toolName ${decision.toolName}`);
+    }
+}
+function validateDelegationTarget(errors, decision) {
+    const target = validateAddressableTarget(errors, 'delegation_request.target', decision.target);
+    if (target?.kind === 'worker_tool') {
+        errors.push('delegation_request.target.kind must not be worker_tool');
+    }
+}
+function validateRecoveryDecision(errors, observation, decision) {
+    validateBoundedString(errors, 'rejectedActionId', decision.rejectedActionId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+    validateBoundedString(errors, 'rationaleSummary', decision.rationaleSummary, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+    if (!observation.policy.allowedFallbacks.includes(decision.selectedFallback)) {
+        errors.push(`recovery selectedFallback ${decision.selectedFallback} is outside allowedFallbacks`);
+    }
+    if (decision.correctedInput !== undefined) {
+        validateBoundedToolInputObject(errors, 'correctedInput', decision.correctedInput, false);
+    }
+}
+function validateStepDependencies(errors, step, stepIds) {
+    if (!step.dependsOn) {
+        return;
+    }
+    const dependencies = new Set();
+    for (const dependency of step.dependsOn) {
+        if (dependencies.has(dependency)) {
+            errors.push(`step ${step.stepId}.dependsOn must not repeat ${dependency}`);
+            continue;
+        }
+        dependencies.add(dependency);
+        if (dependency === step.stepId) {
+            errors.push(`step ${step.stepId}.dependsOn must not reference itself`);
+        }
+        if (!stepIds.has(dependency)) {
+            errors.push(`step ${step.stepId}.dependsOn references unknown step ${dependency}`);
+        }
+    }
+}
+function validateAddressableTarget(errors, field, value) {
+    if (!isRecord(value)) {
+        errors.push(`${field} must be an object`);
+        return null;
+    }
+    const kind = value.kind;
+    validateEnumValue(errors, `${field}.kind`, kind, ADDRESSABLE_TARGET_KIND_VALUES);
+    if (typeof kind !== 'string'
+        || !ADDRESSABLE_TARGET_KIND_VALUES.includes(kind)) {
+        return null;
+    }
+    switch (kind) {
+        case 'durable_agent':
+            validateAllowedRecordFields(errors, field, value, PROVIDER_AGENT_DURABLE_AGENT_TARGET_FIELDS);
+            validateBoundedString(errors, `${field}.agentId`, value.agentId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            validateOptionalEnumValue(errors, `${field}.projection`, value.projection, PROVIDER_AGENT_TARGET_PROJECTION_VALUES);
+            break;
+        case 'execution_target':
+            validateAllowedRecordFields(errors, field, value, PROVIDER_AGENT_EXECUTION_TARGET_FIELDS);
+            validateBoundedString(errors, `${field}.provider`, value.provider, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            validateBoundedString(errors, `${field}.model`, value.model, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            validateOptionalBoundedString(errors, `${field}.control`, value.control, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            break;
+        case 'temporary_participant':
+            validateAllowedRecordFields(errors, field, value, PROVIDER_AGENT_TEMPORARY_PARTICIPANT_TARGET_FIELDS);
+            validateBoundedString(errors, `${field}.participantId`, value.participantId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            validateOptionalBoundedString(errors, `${field}.roleHint`, value.roleHint, PROVIDER_AGENT_MAX_SUMMARY_KEY_LENGTH);
+            validateOptionalBoundedString(errors, `${field}.displayName`, value.displayName, PROVIDER_AGENT_MAX_SUMMARY_KEY_LENGTH);
+            validateOptionalBoundedString(errors, `${field}.avatarHint`, value.avatarHint, PROVIDER_AGENT_MAX_SUMMARY_KEY_LENGTH);
+            break;
+        case 'worker_tool':
+            validateAllowedRecordFields(errors, field, value, PROVIDER_AGENT_WORKER_TOOL_TARGET_FIELDS);
+            validateBoundedString(errors, `${field}.toolName`, value.toolName, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            validateOptionalBoundedString(errors, `${field}.workerProfileId`, value.workerProfileId, PROVIDER_AGENT_MAX_IDENTIFIER_LENGTH);
+            break;
+        default:
+            return null;
+    }
+    return value;
+}
+function validateBudgetEnvelope(errors, budget, field = 'budget') {
+    if (!isRecord(budget)) {
+        errors.push(`${field} must be an object`);
+        return;
+    }
+    validateAllowedRecordFields(errors, field, budget, PROVIDER_AGENT_BUDGET_FIELDS);
+    validateOptionalPositiveNumber(errors, `${field}.maxCostUsd`, budget.maxCostUsd);
+    validateOptionalPositiveInteger(errors, `${field}.maxTokens`, budget.maxTokens);
+    validateOptionalPositiveInteger(errors, `${field}.maxDurationMs`, budget.maxDurationMs);
+    if (budget.maxCostUsd === undefined
+        && budget.maxTokens === undefined
+        && budget.maxDurationMs === undefined) {
+        errors.push(`${field} must include at least one maxCostUsd, maxTokens, or maxDurationMs limit`);
+    }
+    if (budget.hardStop !== true) {
+        errors.push(`${field}.hardStop must be true for provider-agent observations`);
+    }
+}
+function validateSupervisionPolicy(errors, policy) {
+    validateAllowedRecordFields(errors, 'policy.dials', policy, PROVIDER_AGENT_SUPERVISION_POLICY_FIELDS);
+    validateEnumValue(errors, 'policy.dials.autonomy', policy.autonomy, SUPERVISION_AUTONOMY_VALUES);
+    validateEnumValue(errors, 'policy.dials.taskGranularity', policy.taskGranularity, SUPERVISION_TASK_GRANULARITY_VALUES);
+    validateEnumValue(errors, 'policy.dials.toolScope', policy.toolScope, SUPERVISION_TOOL_SCOPE_VALUES);
+    validateEnumValue(errors, 'policy.dials.scaffolding', policy.scaffolding, SUPERVISION_SCAFFOLDING_VALUES);
+    validateEnumValue(errors, 'policy.dials.validation', policy.validation, SUPERVISION_VALIDATION_VALUES);
+    validateEnumValue(errors, 'policy.dials.checkpointCadence', policy.checkpointCadence, SUPERVISION_CHECKPOINT_CADENCE_VALUES);
+    validateEnumValue(errors, 'policy.dials.approvalThreshold', policy.approvalThreshold, SUPERVISION_APPROVAL_THRESHOLD_VALUES);
+    validateEnumValue(errors, 'policy.dials.fallbackPolicy', policy.fallbackPolicy, SUPERVISION_FALLBACK_POLICY_VALUES);
+}
+function validateAllowedFallbacks(errors, allowedFallbacks, policyFallback) {
+    if (!Array.isArray(allowedFallbacks)) {
+        errors.push('policy.allowedFallbacks must be an array');
+        return;
+    }
+    if (allowedFallbacks.length === 0) {
+        errors.push('policy.allowedFallbacks must not be empty');
+    }
+    if (new Set(allowedFallbacks).size !== allowedFallbacks.length) {
+        errors.push('policy.allowedFallbacks must not contain duplicate values');
+    }
+    allowedFallbacks.forEach((fallback, index) => {
+        if (!SUPERVISION_FALLBACK_POLICY_VALUES.includes(fallback)) {
+            errors.push(`policy.allowedFallbacks[${index}] is unsupported: ${fallback}`);
+        }
+    });
+    if (!allowedFallbacks.includes(policyFallback)) {
+        errors.push(`policy.allowedFallbacks must include policy.dials.fallbackPolicy ${policyFallback}`);
+    }
+}
+function validateToolDescriptor(errors, descriptor, index) {
+    if (!isRecord(descriptor)) {
+        errors.push(`availableTools[${index}] must be an object`);
+        return;
+    }
+    validateAllowedRecordFields(errors, `availableTools[${index}]`, descriptor, PROVIDER_AGENT_TOOL_DESCRIPTOR_FIELDS);
+    if (!isRecord(descriptor.manifest)) {
+        errors.push(`availableTools[${index}].manifest must be an object`);
+    }
+    else {
+        validateToolManifest(errors, descriptor.manifest, index);
+    }
+    validateBoundedString(errors, `availableTools[${index}].reason`, descriptor.reason, PROVIDER_AGENT_MAX_TOOL_REASON_LENGTH);
+    if (!descriptor.inputHints) {
+        return;
+    }
+    if (!Array.isArray(descriptor.inputHints)) {
+        errors.push(`availableTools[${index}].inputHints must be an array`);
+        return;
+    }
+    if (descriptor.inputHints.length > PROVIDER_AGENT_MAX_TOOL_INPUT_HINTS) {
+        errors.push(`availableTools[${index}].inputHints must contain `
+            + `${PROVIDER_AGENT_MAX_TOOL_INPUT_HINTS} entries or fewer`);
+    }
+    descriptor.inputHints.forEach((hint, hintIndex) => {
+        validateBoundedString(errors, `availableTools[${index}].inputHints[${hintIndex}]`, hint, PROVIDER_AGENT_MAX_TOOL_INPUT_HINT_LENGTH);
+    });
+}
+function validateToolManifest(errors, manifest, index) {
+    const field = `availableTools[${index}].manifest`;
+    validateAllowedRecordFields(errors, field, manifest, PROVIDER_AGENT_TOOL_MANIFEST_FIELDS);
+    validateBoundedString(errors, `${field}.name`, manifest.name, PROVIDER_AGENT_MAX_TOOL_NAME_LENGTH);
+    validateBoundedString(errors, `${field}.manifestVersion`, manifest.manifestVersion, PROVIDER_AGENT_MAX_TOOL_MANIFEST_VERSION_LENGTH);
+    validateBoundedString(errors, `${field}.description`, manifest.description, PROVIDER_AGENT_MAX_TOOL_DESCRIPTION_LENGTH);
+    validateEnumValue(errors, `${field}.sideEffect`, manifest.sideEffect, SUPERVISED_TOOL_SIDE_EFFECT_VALUES);
+    validateEnumValue(errors, `${field}.preflight`, manifest.preflight, SUPERVISED_TOOL_PREFLIGHT_VALUES);
+    validateEnumValue(errors, `${field}.blocking`, manifest.blocking, SUPERVISED_TOOL_BLOCKING_VALUES);
+    validateEnumValue(errors, `${field}.cancellation`, manifest.cancellation, SUPERVISED_TOOL_CANCELLATION_VALUES);
+    validateEnumValue(errors, `${field}.approval`, manifest.approval, SUPERVISED_TOOL_APPROVAL_VALUES);
+    validateEnumValue(errors, `${field}.evidence`, manifest.evidence, SUPERVISED_TOOL_EVIDENCE_VALUES);
+    validateBoundedStringArray(errors, `${field}.failureCodes`, manifest.failureCodes, PROVIDER_AGENT_MAX_TOOL_FAILURE_CODES, PROVIDER_AGENT_MAX_TOOL_FAILURE_CODE_LENGTH);
+    validateSchemaRef(errors, `${field}.inputSchema`, manifest.inputSchema);
+    validateSchemaRef(errors, `${field}.outputSchema`, manifest.outputSchema);
+    if (manifest.maxBudgetHint !== undefined) {
+        validateBudgetEnvelope(errors, manifest.maxBudgetHint, `${field}.maxBudgetHint`);
+    }
+}
+function readToolDescriptorManifestName(descriptor) {
+    if (!isRecord(descriptor) || !isRecord(descriptor.manifest)) {
+        return null;
+    }
+    return typeof descriptor.manifest.name === 'string'
+        ? descriptor.manifest.name
+        : null;
+}
+function validateObservationSummary(errors, summary, index) {
+    if (!isRecord(summary)) {
+        errors.push(`summaries[${index}] must be an object`);
+        return;
+    }
+    const summaryKey = typeof summary.key === 'string' ? summary.key : String(summary.key);
+    validateAllowedRecordFields(errors, `summary ${summaryKey}`, summary, PROVIDER_AGENT_OBSERVATION_SUMMARY_FIELDS);
+    validateBoundedString(errors, 'summary.key', summary.key, PROVIDER_AGENT_MAX_SUMMARY_KEY_LENGTH);
+    validateEnumValue(errors, 'summary.kind', summary.kind, PROVIDER_AGENT_SUMMARY_KIND_VALUES);
+    if (typeof summary.key === 'string'
+        && /(?:raw|transcript|message|prompt|body|content)/i.test(summary.key)) {
+        errors.push(`summary ${summaryKey} appears to describe raw conversation content`);
+    }
+    validateOptionalBoundedString(errors, `summary ${summaryKey}.sourceRef`, summary.sourceRef, PROVIDER_AGENT_MAX_CONTEXT_REF_LENGTH);
+    if (typeof summary.value === 'string') {
+        validateBoundedString(errors, `summary ${summaryKey}`, summary.value, PROVIDER_AGENT_MAX_SUMMARY_TEXT_LENGTH);
+        return;
+    }
+    if (typeof summary.value !== 'number'
+        && typeof summary.value !== 'boolean'
+        && summary.value !== null) {
+        errors.push(`summary ${summaryKey}.value must be number, string, boolean, or null`);
+    }
+}
+function validateToolName(errors, toolName, availableToolNames, field) {
+    validateRequiredString(errors, `${field}.toolName`, toolName ?? '');
+    if (toolName && !availableToolNames.has(toolName)) {
+        errors.push(`${field}.toolName ${toolName} is outside the bounded tool surface`);
+    }
+}
+function validateRequiredString(errors, field, value) {
+    if (typeof value !== 'string') {
+        errors.push(`${field} must be a string`);
+        return false;
+    }
+    if (value.trim().length === 0) {
+        errors.push(`${field} is required`);
+        return false;
+    }
+    return true;
+}
+function validateEnumValue(errors, field, value, allowedValues) {
+    if (typeof value !== 'string' || !allowedValues.includes(value)) {
+        errors.push(`${field} is unsupported: ${String(value)}`);
+    }
+}
+function validateOptionalEnumValue(errors, field, value, allowedValues) {
+    if (value === undefined || value === null) {
+        return;
+    }
+    validateEnumValue(errors, field, value, allowedValues);
+}
+function validateBoundedString(errors, field, value, maxLength) {
+    if (!validateRequiredString(errors, field, value)) {
+        return;
+    }
+    if (value.length > maxLength) {
+        errors.push(`${field} must be ${maxLength} characters or less`);
+    }
+}
+function validateOptionalBoundedString(errors, field, value, maxLength) {
+    if (value === undefined || value === null) {
+        return;
+    }
+    validateBoundedString(errors, field, value, maxLength);
+}
+function validateBoundedStringArray(errors, field, values, maxEntries, maxLength) {
+    if (!Array.isArray(values)) {
+        errors.push(`${field} must be an array`);
+        return;
+    }
+    if (values.length > maxEntries) {
+        errors.push(`${field} must contain ${maxEntries} entries or fewer`);
+    }
+    values.forEach((value, index) => {
+        validateBoundedString(errors, `${field}[${index}]`, value, maxLength);
+    });
+}
+function validateBoundedJsonValue(errors, field, value, depth = 0, seen = new WeakSet()) {
+    if (value === null || typeof value === 'boolean') {
+        return;
+    }
+    if (typeof value === 'string') {
+        if (value.length > PROVIDER_AGENT_MAX_TOOL_INPUT_STRING_LENGTH) {
+            errors.push(`${field} must be ${PROVIDER_AGENT_MAX_TOOL_INPUT_STRING_LENGTH} characters or less`);
+        }
+        return;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            errors.push(`${field} must be a finite number`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        validateBoundedJsonArray(errors, field, value, depth, seen);
+        return;
+    }
+    if (isRecord(value)) {
+        validateBoundedJsonObject(errors, field, value, depth, seen);
+        return;
+    }
+    errors.push(`${field} must be JSON-compatible`);
+}
+function validateBoundedToolInputObject(errors, field, value, required) {
+    if (value === undefined) {
+        if (required) {
+            errors.push(`${field} must be an object`);
+        }
+        return;
+    }
+    if (value === null) {
+        errors.push(`${field} must be an object`);
+        return;
+    }
+    if (!isRecord(value) || !isPlainJsonObject(value)) {
+        errors.push(`${field} must be an object`);
+        return;
+    }
+    validateBoundedJsonValue(errors, field, value);
+}
+function validateBoundedJsonArray(errors, field, value, depth, seen) {
+    if (depth >= PROVIDER_AGENT_MAX_TOOL_INPUT_DEPTH) {
+        errors.push(`${field} must not exceed depth ${PROVIDER_AGENT_MAX_TOOL_INPUT_DEPTH}`);
+        return;
+    }
+    if (seen.has(value)) {
+        errors.push(`${field} must not contain circular references`);
+        return;
+    }
+    seen.add(value);
+    if (value.length > PROVIDER_AGENT_MAX_TOOL_INPUT_ARRAY_ITEMS) {
+        errors.push(`${field} must contain ${PROVIDER_AGENT_MAX_TOOL_INPUT_ARRAY_ITEMS} entries or fewer`);
+    }
+    value
+        .slice(0, PROVIDER_AGENT_MAX_TOOL_INPUT_ARRAY_ITEMS)
+        .forEach((entry, index) => validateBoundedJsonValue(errors, `${field}[${index}]`, entry, depth + 1, seen));
+    seen.delete(value);
+}
+function validateBoundedJsonObject(errors, field, value, depth, seen) {
+    if (depth >= PROVIDER_AGENT_MAX_TOOL_INPUT_DEPTH) {
+        errors.push(`${field} must not exceed depth ${PROVIDER_AGENT_MAX_TOOL_INPUT_DEPTH}`);
+        return;
+    }
+    if (!isPlainJsonObject(value)) {
+        errors.push(`${field} must be a plain JSON object`);
+        return;
+    }
+    if (seen.has(value)) {
+        errors.push(`${field} must not contain circular references`);
+        return;
+    }
+    seen.add(value);
+    const entries = Object.entries(value);
+    if (entries.length > PROVIDER_AGENT_MAX_TOOL_INPUT_OBJECT_KEYS) {
+        errors.push(`${field} must contain ${PROVIDER_AGENT_MAX_TOOL_INPUT_OBJECT_KEYS} keys or fewer`);
+    }
+    entries
+        .slice(0, PROVIDER_AGENT_MAX_TOOL_INPUT_OBJECT_KEYS)
+        .forEach(([key, entry]) => {
+        if (key.trim() === '') {
+            errors.push(`${field} keys must not be blank`);
+            return;
+        }
+        if (key.length > PROVIDER_AGENT_MAX_TOOL_INPUT_KEY_LENGTH) {
+            errors.push(`${field} keys must be ${PROVIDER_AGENT_MAX_TOOL_INPUT_KEY_LENGTH} characters or less`);
+            return;
+        }
+        validateBoundedJsonValue(errors, `${field}.${key}`, entry, depth + 1, seen);
+    });
+    seen.delete(value);
+}
+function validateOptionalPositiveNumber(errors, field, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        errors.push(`${field} must be greater than 0`);
+    }
+}
+function validateOptionalPositiveInteger(errors, field, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        errors.push(`${field} must be a positive integer`);
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isPlainJsonObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=providerAgentDecision.js.map